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PREFACE 

This manual describes version 2 of APL on both the TOPS-10 and TOPS-20 
operating systems. There are two implementations of APL on each sys- 
tem, APL-Basic and APLSF (System Functions) . APLSF is a superset of 
APL-Basic. To distinguish APLSF from APL-Basic, we have shaded the 
text describing features available only in APLSF. 

This document is not an APL tutorial manual. Therefore, if you are 
unfamiliar with the APL language, you should read an APL primer before 
reading this manual. Also, because you will be using APL in conjunc- 
tion with either TOPS-10 or TOPS-20, you should have the latest edi- 
tions of the following documents on hand: 

1. TOPS-20 User's Guide 

2. TOPS-20 Monitor Calls Reference Manual 

or 

3 . TOPS-10 Operating System Commands Manual 

4. TOPS-10 Monitor Calls Reference Manual 
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Conventions Used In This Manual 



» 



I 1 



Special square brackets indicating operational 
information that can be omitted from a command 
string. 

Braces indicating a choice. Choose one from 
the enclosed. 



Lowercase letters 



UPPERCASE LETTERS 



Lowercase characters in a command string indi- 
cating variable information you supply. 

Uppercase characters in a command string indi- 
cating fixed (literal) information that you 
must enter as shown. 



Examples 



All examples were produced on an LA37 using 
either TOPS-10 or TOPS-20. 



Contrasting Colors 



APL 



Red - Where examples contain both user input 
and computer output, the characters you type 
are in red; the characters APL prints are in 
black. 

Gray - The text shaded in gray or printed on 
gray stock indicates the features available 
only with APLSF. 

Refers to both APL-Basic and APLSF. 
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CHAPTER 1 
THE APL OPERATING ENVIRONMENT 



1 . 1 INTRODUCTION 

APL (A Programming Language) is a language interpreter that runs under 
the control of either of two operating systems, TOPS-10 or TOPS-20. 
The TOPS-10 and TOPS-20 operating systems provide the APL user with 
standard timesharing features, such as resource allocation, job con- 
trol, device handling, and usage accounting. 

Because APL is a very compact programming language, it is suited for 
handling numeric and character array-structured data. In addition to 
its mathematically concise format, APL is also an efficient general 
data-processing language. 

APL is a 2-segment system. The code segment or shared segment, is 
the APL interpreter consisting of code shared among all APL users. 
The data segment is the APL user's workspace. Each user has a data 
segment, but there is only one copy of the interpreter. 



1.1.1 Workspaces 

A workspace is a block of storage where all interaction with APL takes 
place. Each time you access APL, you are issued a clear workspace in 
which to define variables and functions as well as to execute APL 
statements. The size of an APL workspace is dynamic and can vary from 
2K to 176K 36-bit words on TOPS-10. On TOPS-20, the figure is express- 
ed in pages of 36-bit words, 4P to 352P. The default workspace size 
is 20K on TOPS-10 and 4 OP on TOPS-20. If you need to change the size, 
refer to the )MAXCORE command. Section 5.3.1. 

There are three states your workspace can assume as you proceed 
through an APL session: 

1. Clear workspace 

2. Active workspace 

3. Inactive workspace 

At the beginning of an APL session, you are given a fresh workspace: 
the clear workspace. It has no open files, no defined variables or 
functions; it has a clear (empty) symbol table, and a clear (empty) 
state indicator. System variables are set to their default values. 
Once you start typing information into your workspace, it is no longer 
clear. The workspace you are currently using is your active workspace. 
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All functions and variables you define during the current APL session 
are stored temporarily in this workspace. You can save an active 
workspace as a file, in binary format, on a secondary-storage device, 
such as a disk or magnetic tape. An active workspace becomes an in- 
active workspace when you save it. You can save several workspaces 
in your disk area; however, only one can be active at any one time. 
As a group, inactive workspaces are known as a private library. 

When you save a workspace, you are not only saving functions and vari- 
ables, but also the APL symbol table, state indicator and some system 
variable settings. When you retrieve an inactive workspace from your 
library, it again becomes your active workspace. 

A workspace can be named, copied, saved, retrieved, deleted, renamed, 
protected, and cleared. These workspace operations are described in 
Chapter 5 . 



1.1.2 Data Files 



In addition to workspaces, APL provides another way to store and re- 
trieve information: the data file. A data file is a collection of 
related elements stored in the form of records. You determine the 
size and content of the records, and the structure and access pro- 
perties of the file. 

APL can handle four types of files: 

1. ASCII Sequential 

2. Internal Sequential 

3. Direct Access 

4. Binary Access 

Refer to Chapter 7 for a description of data files. 



1 . 2 HARDWARE 

The APL language consists of a special character set in which Greek 
letters and a variety of other special characters represent APL lan- 
guage functions and operators. Examples of such special characters 
include i, D, V, and e. 

TOPS-20 and TOPS-10 support a variety of terminals for use with the 
APL system. Some terminals provide keyboards with the full APL char- 
acter set (such as the LA37 in Figure 1-1). However, terminals with- 
out the APL keyboard can also be used to access APL. On non-APL 
terminals, you can use a special set of keyword mnemonics to represent 
APL symbols. See Table 1-2 for both character sets. 

You select the APL character set or the mnemonic character set when 
you begin an APL session. APL prompts you with: 

■terminal » ♦ 
You respond with one of the terminal designators listed in Table 1-1. 
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Table 1-1 
APL Terminals and Designators 



Terminal 


Designator 


IBM Selectric^ -type 

terminal with APL 

typing element, or equivalent 


2741 


Bit-paired ASCII/APL terminal 


BIT 


Key-paired ASCII/APL terminal 


KEY 


DECwriter II model LAS 6 with 
APL option (LAS 7) 


LAS 6 


Tektronix^ 4013 


4013 


Tektronix^ 4015 


4015 


Any terminal without 
APL character set 


TTY /terminal 



^Selectric is a registered trademark of IBM. 
^Tektronix is a registered trademark of Tektronix, Inc. 

The /terminal switch with the TTY designator can be any one of the 
other terminal designators in Table 1-1, for example TTY/BIT. This 
switch is optional. It takes effect when you use the ) OUTPUT command 
(Section 7.9) . 

When you specify LA36, 4013, or 4015, that designator causes character 
font-switching sequences to be sent to the terminal when you enter and 
leave APL. This means that you do not have to manually switch charac- 
ter sets by pushing a button on the terminal. Specification of KEY 
does not have this effect. 



1.2.1 APL-Keyboard Terminals 

The keyboard illustrated in Figure 1-1 is a typical APL-keyboard ter- 
minal; you can use it in either ASCII or APL mode. When you access 
APL, the characters are received and interpreted by the APL system. 
Note that letters, numbers, and some of the special characters appear 
in the conventional keyboard positions. In APL mode, the letters print 
only in uppercase and are produced only when the keyboard is not shift- 
ed. The full APL character set is described in Table 1-2. 
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ESC 
(SEU 



t^ 



@ 

2 



z^vz^l 



$ 
4 



0/ 

/o 

5 



^i^^i^^ijj^ 



& 

7 



rF 



8 







L^^^ 



+ 



BACK 
SPACE 



\t 



BREAK 



ATTN 



TAB 



Q 



W 



R 




I 



U 



^^ 






VI 



l>z^l>i^i>^lalt:^ 



LINE 
FEED 



CTRL 



I 



CAPS 
LOCK 



A 




D 



:^ 



BELL 



H 



J 



l^ 



VT 

K 



FF 



m 



1 I 

! 



I 



RETURN 






L^^ 



V 




N 



M 



< 



^^E^^ 



> 



I 



SHIFT 



REPEAT 



^ 



MR-S-229-79 



1-3 
H 
> 
tr" 
O 



Figure 1-1 The APL Keyboard (LA37 Terminal) 
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1.2.2 Terminals Without the APL Keyboard 

If you do not have a terminal with an APL keyboard, you can use a com- 
bination of keyword mnemonics, or escape characters, and ASCII charac- 
ters to interact with the APL interpreter. First, you respond with 
TTY when APL prompts for a terminal designator (Section 1.2). Then you 
can input any of the keyword or escape-mode equivalents listed in 
Table 1-2. 

For example, to represent the APL rho symbol (p), either type the 
mnemonic .RO or the escape character @R. To type a character in es- 
cape mode, first type the at sign (@) and then enter the desired upper- 
case character. No delimiting blanks are necessary, and you can mix 
the two input modes freely. 

APL output can also be displayed in either keyword or escape modes, 
but you must select one or the other; they cannot be mixed. The )MODE 
command allows you to select the output mode. This is where the TTY 
/terminal is relevant. See Section 5.5.3. 



1.3 THE APL CHARACTER SET 

Table 1-2 lists all APL characters available on TOPS-10 and TOPS-20. 
The first column lists the APL character set. The second column, TTY 
set, lists the keyword mnemonic equivalents. The third column supplies 
names commonly associated with APL characters, and the fourth column 
lists the escape characters. The uppercase letters indicate the ori- 
gin of the mnemonic representation. 

The second section of the table lists APL overstruck characters. These 
are characters constructed by typing one character, one backspace, then 
a second character on top of the first. For example, to construct the 
logarithm symbol (®) , type the circle symbol (o) , then backspace, then 
type the exponentiation symbol (*) . You can also type the exponenti- 
ation symbol (*) before the circle symbol (o) ; the order is not signi- 
ficant. On non-APL keyboard terminals, overstruck characters are re- 
presented by single-strike characters or by keyword mnemonics. Notice 
that dollar appears as both a single-strike and an overstruck charac- 
ter. On some terminals you can enter dollar as a single-strike char- 
acter ($) , and on other terminals you must enter dollar as an over- 
struck character (-Si). 
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Table 1-2 
APL Character Set 





S 


ingle-Strike Characters 




APL Set 


TTY Set 


Name 




Escape Mode 


A-Z 


A-Z 


alphabet 






0-9 


0-9 


numbers 






+ 


+ 


add 






A 


& 


and 






-^ 


/ 


assignment 
(back-arrow or und( 
concatenate 
colon 


2rline) 




^ 


% 


divide 






$ 


$ 


dollar format 






= 


= 


equal to 






\ 


\ 


expand (scan) 






* 


* 


exponentiate 




@P 


> 


> 


greater than 






[ 


[ 


left bracket 






( 


( 


left parenthesis 






< 


< 


less than 






X 

t 


# 

1 


multiply 
quote string 




(aK 


9 


? 


question (roll and 


deal) 


(§0 


/ 


/ 


reduce 






] 


] 


right bracket 






) 


) 

7 


right parenthesis 
semicolon 






- 


- 


subtract 






+ 


/s 


take 




@Y 


1 


.AB 


residue (ABsolute value) 


(ajM 


a 


.AL 


ALpha 




(SA 


D 


.BX 


quad (Box) 




@L 


r 


.CE 


CEiling (maximum) 




(as 


i 


.DA 
.DD 


drop (Down Arrow) 
Dieresis 




@U 


1 


.DE 


DEcode 




(SB 


V 


.DL 


DeL 




@G 





.DM 


DiaMond 






n 


.DU 


Down Under 




@c 


T 


.EN 


ENcode 




m 


e 


• EP 


EPsilon 




@E 


L 


.FL 


FLoor 




(§0 


> 


.GE 


Greater than or Equal to 




-> 


.GO 


GO to (branch) 






I 


.10 


iota 




@i 


{ 


.LB 


Left curly Brace 






A 


.LD 


delta (Lower Del) 




(an 


< 


.LE 


Less than or Equal 


to 




1- 


.LK 


Left tacK 






o 


.LO 


circle (Large 0) 




(30 


3 


.LU 


Left Union 




(ax 


?i 


.NE 


Not Equal to 
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Table 1-2 (Cont.) 
APL Character Set 



Single-Strike Characters 


APL Set 


TTY Set 






Name 


Escape Mode 


- 


.NG 




NeGation 




n^ 


.NT 




Not 




@T 


0) 


.OM 




OMega 




@W 


V 


.OR 




OR 






} 


.RB 




Right 


curly Brace 




p 


.RO 




RhO 




@R 


H 


.RK 




Right 


tacK 




c 


.RU 




Right 


Union 


@Z 


o 


.SO 




jot (Small 0) 


@J 




.US 




Underscore 


@F 


u 


.uu 




Up Union 


@V 






Ove 


rstruck Characters 








(None in Escape Mode) 






Characters 


to 






APL Set 


Strike 


Over 


TTY Set 


Name 


I 


S 


1 




$ 
1 


dollar (format) 
factorial (shriek) 


t 


V 


1 




.GD 


Grade Down 


4. 


A 


1 




.GU 


Grade Up 


I 


± 


T 




.IB 


I-Beam (histogram) 


® 


o 


* 




.LG 


LoGarithm 


TV 


A 


~ 




.NN 


NaNd 


V 


V 


/•^ 




.NR 


NoR 


\ 


\ 


- 




.CB 


back expansion 


e 


O 


- 




.CR 


(Circle) Rotate 


/ 


/ 


- 




.CS 


back scan 


i 


D 


V 




• DQ 


Divide Quad 


S 


D 


-(r 




• IQ 


Input Quad 


a 


D 


-> 




.OQ 


Output Quad 


BJ 


U 


T 




.OU 


out 


¥ 


V 


~ 




.PD 


Protected Del 





D 


V 




.QD 


Quad Del 


B 


D 


t 




.QQ 


Quote Quad 


4> 


o 


1 




.RV 


Reversal 


^ 


o 


\ 




.TR 


TRanspose 


4 


± 


o 




.XQ 


execute 


T 


T 


o 




.FM 


ForMat 


R 


n 


o 




II 


Comment (lamp) 


d-2 


A-Z 


_ 




.ZA-.ZZ 


underscored alphabetics 


A 


A 


- 




.Z@ 


underscored lower del 
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1.4 INTERACTING WITH APL 

APL provides easy-to-use commands to allow you to interact with the 
operating system. Sections 1.4.1 through 1.4.4 describe some of the 
commands available. Chapter 5 discusses APL system commands. 



1. 4.1 Entering APL Command Level (Starting the Session) 

To access APL, first log in to either TOPS-20 or TOPS-10. After a 
successful log in, type the following on TOPS-20: 

©APLSr 

On TOPS-10, type: 

♦R APLSF 

In both cases, APLSF begins the session by asking for your terminal 
designator : 

tfsririirial ♦ ♦ 
If you are unsure of what to respond, type H (for Help). For example: 

bermii. nal ♦ « h 

«5:i. ve the approp relate response for your t e vmti ;i. n a I 

r^ e s p o I'l s e y o u r t e r in :i. ri a I 

274:1.1 jj;,,j, 2741 or s :i. m :i. 1 a r w;i.th a pi ball 

bit as c i :i. b p 1 b 1 1 p a i v i n <:i 

k e \:{ B s c :i. :i. a p 1 k e •-.■.{ p a :i. r i n <:■?, 

la 36 la 36 with apl character set option 

4013 tektronix 4013 

4015 tektronix 4015 

tty anw terminal not havin:^ apl font 

TFRMINAL, « 



After receiving a valid terminal designator, APL responds with a 
greeting and identification message. It then supplies a clear work- 
space for use during the current APL session, or automatically loads 
the special CONTINUE workspace saved from the last APL session, if 
such a workspace exists in your disk area. (See Section 5.6.2 for a 
description of the CONTINUE workspace.) If a clear workspace is sup- 
plied, APL displays the message: 

ci...ih:ap: ws 

If the CONTINUE workspace is loaded, APL outputs a standard load 
workspace message. For example: 

(i?aplsf 
terminal ♦ ♦ la 

'^''•■'•-•■20 t'ECSYSTEM~20 APL.SF 2(407) 

■T'TY22) 15:22:57 TUESXIiAY 2 6 •-"■"•<■■ 7 9 MASELLA 

SAVEfi 15:22:39 26-^^>fi"79 5»=- 



^The 2741 is supported only on TOPS-10 
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APL indents six spaces to signify that it is ready to accept input. 
APL outputs at the left margin but automatically indents six spaces 
before echoing your input. The first character you type will print in 
the seventh column from the left margin. APL thus clearly differen- 
tiates between what it prints out and what you type in. 



1.4.2 Ending the Session 

To log off the system while in APL mode, use one of the following 
commands : 

)OFF- ends the session and logs you off the system. 

)cdnt:i:huk: ends the session, logs you off the system, and 
stores the active workspace under the name 
DSKiCONTIN .APL. This workspace, instead of a 
clear workspace, will be loaded the next time 
you run APL. 

Note that APL commands begin with a right parenthesis. These com- 
mands, )OFF and )CONTINUE , are described in Sections 5.6.4 and 5.6.2, 
along with a description of options available for automatically re- 
turning to system command level after ending a session rather than 
logging off. 

CAUTION 

Do not end a work session by disconnecting 
the terminal ' s telephone connection or 
the current workspace will be lost. 



1.4.3 Returning to System Command Level 

To return to system command level during an APL session, type the )MON 
command. APL indicates that control has been returned to the oper- 
ating system by printing: 

monitor; 

When you receive the system prompt, you can then perform a variety of 
system operations, including sending and receiving messages to or from 
other users and the operator, assigning devices to your job, inquiring 
about CPU usage, and performing other standard functions. 

CAUTION 

If you run any other program, the 
workspace in memory will be destroyed. 

To return to APL with the workspace intact, type CONTINUE . APL re- 
sponds with APLSF: to indicate that it has again received control. 
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1.4.4 Interrupting Execution 

To interrupt APL during an operation, use the attention signal, CTRL/C. 
Two CTRL/Cs interrupt function or program execution and return you to 
APL mode. The response may be delayed for a few seconds because of 
system buffering. 

Typing five CTRL/Cs will return you to system command level. To return 
to APL mode and resume APL operations, type one of the following oper- 
ating system commands: 

^REENTER 

or 

^CONTINUE 



1.5 KEYBOARD EDITING 



The following sections describe the procedures for entering and cor- 
recting APL text on a terminal with an APL keyboard. 



1. 5.1 Correcting a Line Before Entering 

You can type characters in an APL input line in any order. Regardless 
of how you enter the line, APL evaluates it exactly as it appears on 
the terminal; the order in which you type characters is not significant 
By using the appropriate space and backspace characters, you can even 
type the line backwards. APL interprets the line only when you press 
the RETURN key. (This "random order" feature is not available on TTY 
terminals. ) 

An APL line can contain up to 390 characters. This total includes 
spaces and backspaces. If you type more characters than the limit and 
press RETURN, APL ignores the line and sends the error message: 

49 INPUT HHE TOO L.OHG 

For a complete list of APL messages, refer to Appendix A. 

NOTE 

Backspacing is a method for positioning 
the carriage, it does not cause char- 
acters to be erased or ignored by APL. 

On an APL-keyboard terminal, if you discover an error in a line before 
you press the RETURN key, you can backspace to the error and press the 
LINEFEED key. Everything from the LINEFEED to the right is ignored by 
APL. You can then complete the line directly below the part in error 
by retyping it. For example: 

Cf- ' f;:h;:k:::i:ve" backspace 4 then line feed 
cki:ivih: • 

Hi:ECiH::i;vE 
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There are several special characters available with which to make cor- 
rections. Table 1-3 lists these characters and their meaning. 



Table 1-3 
Editing Characters 



Character 



Meaning 



CTRL/C 



CTRL/U 



CTRL/0 
CTRL/R 

LINEFEED 

DELETE (RUBOUT) 



Two CTRL/Cs interrupt APL function execution 
and expression evaluation. Five CTRL/Cs re- 
turn you to system command level. 

Deletes the current input line and positions 
you in column one of the next line. It does 
not delete past the first LINEFEED it en- 
counters. Echoes as XXX on TTYs and as =>=>=> 
on LAs . 

Suppresses output to the terminal. 

Performs a LINEFEED and displays the cor- 
rected line starting at column one. 

In conjunction with backspace, it deletes 
input. 

Deletes one character at a time. On an LA, 
echoes one h character on TOPS-10 for entire 
operation. Echoes one h character for every 
character deleted. The f- prints as a \ on 
a TTY. 



1.5.2 Correcting a Line After Entering 

An APL statement entered and processed in immediate mode can be edited 
according to the same line-editing rules established for user-defined 
functions. These rules are described in Sections 6.3.7 and 6.3.8. 
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LANGUAGE SYNTAX 



2 . 1 INTRODUCTION 

This chapter describes the syntax that governs the construction of APL 
statements and expressions, including statement components, data types, 
and expression evaluation. 



2.1.1 Statement Execution Modes 



Two execution modes are available in APL: 



1. Immediate mode, in which APL executes statements and express- 
ions as soon as you enter them and press the RETURN key. 

2. Function-execution mode, in which APL executes the statements 
contained in a user-defined function (Chapter 6) . APL enters 
function-execution mode whenever it discovers a user-defined 
function in the statement it is currently executing, and 
exits from function-execution mode when the last statement in 
the function is executed, you suspend the function, or an 
error occurs. 

The statement syntax is identical in both modes; however, there are a 
few special characters that are not generally relevant in immediate 
mode, but useful in function-definition mode. These characters are 
described in Chapter 6. Most of the examples in this chapter illus- 
trate immediate-mode execution. Chapter 6 describes function- 
definition mode, in which you prepare and edit functions, and function- 
execution mode, in which you actually execute the function. 

In immediate mode, APL clearly differentiates between what you type 
and what it prints. APL always indents six spaces before accepting 
input. After you enter text, press the RETURN key to indicate that 
entry is complete. APL processes your input and, if necessary, prints 
results beginning at the left margin. After printing output, APL then 
performs a carriage return/line feed and indents six spaces. For 
example: 

6 

EM- 9 

9 
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You can have up to 390 characters in a single line. This count 
includes spaces and backspaces. 



2 .1.2 Expression Components 

An APL expression can consist of the following components 

1. Identifiers 

Variables, Section 2.1.2.1 
Labels, Section 6.4.2 
User-defined Functions, Chapter 6 
Groups, Section 5.1.3.4 

2. Constants 

Numeric, Section 2.1.2.2 
Character, Section 2.1.2.2 

3 . Characters 

I/O Functions, Section 2.5 

Primitive Scalar Functions, Section 3.2 

Primitive Mixed Functions, Section 3.3 

Extended Functions, Section 3.4 

File Functions, Chapter 7 

Operators, Section 3.5 

4. System Variables, Section 4.2 
System Functions, Section 4.3 



2.1.2.1 Identifiers - An identifier can be a variable name, a label 
name, or a user-defined function name. It can consist of any number 
of letters and digits; however, the first character must be a letter. 
APL defines a letter, in this case, as any character A through Z, A 
through Z, A and A. Only the first 31 characters of the identifier 
are significant, and embedded spaces are not allowed. APL truncates 
all identifiers to 31 characters; therefore, you cannot create an 
identifier longer than 31 characters. For example: 

Legal Identifiers Illegal Identifiers 

A»C63»8 J.«c75 (does not begin with a letter) 
a74 "^-^a Z6 (contains an embedded space) 

^(5956Ha P''5'742JE' (contains invalid character V) 

Note that you cannot start an identifier with the characters Sh or TA 
because of a conflict with the trace and stop vectors. Refer to 
Sections 6.4.5 and 6.4.6. 

A variable must contain a value before you can reference it. Other- 
wise, you will receive the message 11 VALUE ERROR from APL. Section 
2.1.5 describes how to assign values to variables. 

Variable names and their positions have special meaning in function- 
definition mode. Refer to Chapter 6 for this information. 
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2.1.2.2 Constants - Constants can be either numeric or character data. 
A numeric constant is one or more decimal digits with an optional 
decimal point. A numeric constant can also be in exponential format; 
an integer or decimal quantity followed by E and the power of ten by 
which the quantity is to be multiplied. All of the following constants, 
for example, are valid representations of the same value. 

712 712.0 7120i5:"l 7.12^2 

Wherever possible, APL prints numbers without decimal points and 
exponents. 

7:1.2 712.0 7 120^'" 1 . 7 . 12^-2 

7:1.2 7:1.2 7:1.2 7:1.2 



In APL, you represent a negative number by a numeric constant preceded 
by a negative sign ("") . This sign is a distinctive symbol (uppercase 
2) . It is not the same character as the minus sign (-) which is used 
to indicate subtraction. On non-APL terminals, the negative sign is 
.NG. 

A character constant is one or more alphanumeric and/or special char- 
acters (including carriage returns and line feeds) enclosed in single 
quotation marks. For example: 

■ GEORGE- ' 

' V H X S :i S A C O W <J> T A N T ' 

When APL prints a character constant, it omits the enclosing quotation 
marks. If you want APL to output quotation marks, type one extra 
single quotation mark next to the one you want to print. For example: 



Bf ' TOHY ' < S TEHHIS RACQUET ' 
B 
T C) W Y ' S T E H N X. <:> Hi: A C G IJ E T 



Numeric and character data can be structured in a variety of ways 
APL supports the following types of data: 

1. scalars 

2. vectors 

3. matrices 

4. arrays of three or more dimensions 
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A scalar is a single numeric or character value with no dimensions 
E'or example: 



32 



32 



A vector is a 1-dimensional array or character string consisting of 
any number of values. Enter a numeric vector as a list of values 
separated by at least one space. For example: 

Hfl 2 3 4 5 
n 

12 3 4 5 

In this example, H is defined as a vector whose elements are 1, 2, 3, 
A, and 5. APL stores the values in the order in which you enter them. 

A character vector or literal vector is entered as a string of char- 
acter constants enclosed in single quotation marks. Unless you want 
the space character as part of the character vector, do not insert 
spaces between characters in the vector. Note the following example: 

A <•• ' A B C D K: F Cv h x u k l. m h o f- ' 

A 
ABCDEFG HIJKL-MNDP 

Because any characters, including carriage returns and line feeds, can 
be elements of a character constant, you can also enter several lines 
of character data as a 1-character vector. For example: 



Af. 'THIS IS A 
MUUTIPUnn I..XHB. 
U XTKRAL. , ' 

A 
THIS IS A 
MULTIPL-K I.- I HE 
L. ITERAL. J 

Although there are several lines of text, A is still a vector. 

Note that a common error occurs when you type a character constant 
with an unbalanced number of quotation marks. APL thinks that you are 
still defining the constant when you press RETURN to enter the line. 
Consequently, APL includes the carriage return/line feed as part of 
the constant. You can spot this error by noticing that APL does not 
indent six spaces when you press the RETURN. Typing a single quotation 
mark will usually get you out of this situation. 
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A matrix is a 2-dimensional array consisting of rows and columns. APL 
supports the use of matrices as well as arrays of higher dimensions. 

The rho character is used to .create and reshape arrays (Sections 3.3.18 
and 3.3.15). You enter values corresponding to each element of an 
array and also the shape or size of the array. The following examples 
show array output. (To input arrays, refer to Section 3.3.15.) 

The following is a numeric matrix with 2 rows and 3 columns. 



A 

1 2 3 
4 5 6 

APL also supports arrays of three dimensions or more. For all practi- 
cal purposes, there is no intrinsic limit on the number of dimensions 
in an APL array. The only restriction is that the size of the array 
cannot exceed your workspace size. If you have unlimited memory avail- 
able, the maximum number of dimensions allowed is 2*18. 

The following is an example of a 3-dimensional character array. Note 
that APL inserts a blank line between each plane greater than two. 



A f • ' A B c t> e: f g H 1 ..) K I.. M ti O I"- C* R i)> T u V w X r -z ' 
2 3 4^^ 

ABCri 
E F" G H 
1 J K I.- 

MNOP 
GRST 
UVWX 



2.1.3 Spaces and Comments 

Spaces are usually not significant in APL. Therefore, you need not 
separate functions from constants or variables. This is also true on 
non-APL-keyboard terminals. The mnemonics for operators need not be 
preceded or followed by a space. The following expressions are equi- 
valent: 





» i- 




Ci-16 




f.U-.Bil-C 




A ir 




*TR B 


35 






♦ TRB 


35 
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Spaces are also not required between a succession of functions or oper- 
ators. For example: 



AMtr-*/B 



However, spaces must be included to separate names of adjacent user- 
defined functions, constants, and variables. For example, they are 
required when you are entering a series of numeric constants as a 
vector. The spaces included in the following example are necessary; 



2 TP:iG 3 (user-defined function) 
»<-3 4 5 (numeric vector) 



You can also use comments in APL. Their use is particularly relevant 
in function-definition mode. Comments must appear on separate lines; 
they may not be included on lines containing APL statements. The first 
character in a comment line is the lamp character (fl), formed by over- 
striking the down union character (n) with the jot character (°). 
Section 6.2.4 describes comment lines in greater detail and illustrates 
their use in a variety of user-defined functions. On non-APL-keyboard 
terminals, use a double quotation mark for the comment character. 



2.1.4 File Specifications 

File specifications indicate to the operating system when to locate 
and identify a file. Certain operations in APL require you to supply 
a file specification in the syntax (for example, when you assign a 

|i|p|||gijp|||^i|||i|5^ 4.1). 

The complete form of a file specification is: 



dev: f ilename.extC directory ]<prot> 



where 



dev; 



is a device name, or a logical name you have 
defined. See Appendix D for defining logical 
names. 



filename 

. ext or . typ 

[directory] 



<prot> 



is one to six alphanumeric characters specifying 
a particular file in the directory. 

is one to three alphanumeric characters identify- 
ing the contents of the file. 

is the project-programmer number of the owner of 
the directory. You can translate a directory 
name on TOPS-20 to its corresponding project- 
programmer number by using the TRANSLATE command, 
See Appendix D for this information. 

is a 3-digit octal protection code specifying 
who can read and write the file. 
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You need not give the entire file specification in every case. The 
defaults are: 

Argument Default 

dev: DSK: 

filename No default; it must be specified 

.ext or .typ Depends on the type of file 

[directory] Your currently connected directory 

<prot> Installation-dependent 

2.1.5 Statement Types 

There are two general types of APL statements: 

1. Branches constructed with -> 

2. Assignments constructed with -^ 

Branch statements restart a function and transfer control from one part 
of a function to another. These statements are most relevant in the 
context of user-defined functions and are described in Section 6.4.1. 

Assignment statements store one or more values into an identifier. The 
general form of an assignment statement is illustrated by the following: 



where 2+5 is an APL expression 

-«- is the assignment function 
A is a variable name 

You can have more than one statement on a line by separating each with 
a semicolon. Each statement separated must contain a value. For 
example : 

c<- A-f» J Af 64 y E<f-92 
c 
V56 

Assignment statements are, themselves, expressions and can be used in 
the construction of other statements. The following example illustrates 
a method of assigning values to more than one variable with a single 
statement: 

A<..3t.K<f.4tCf.7 
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Here the value 7 is assigned to C, 11 to B, and 14 to ^ . The express- 
ion is evaluated from right to left according to the rule described in 
Section 2.1.5. 

In any mode, if you do not include an assignment or branch function in 
an expression, APL prints the results on the terminal when the express- 
ion is executed. For example: 

2+3 



This type of expression has the effect of an implied print statement 
in APL. 



2.1.6 Evaluation of APL Statements and Expressions 

APL evaluates unparenthesized statements and expressions in strict 
right-to-left order, regardless of the particular functions in the 
statement. Unlike some languages, which perform multiplication and 
division before addition and subtraction, APL has no explicit function 
precedence. For example, APL evaluates the expression 



3x4+5 
27 



as 27, using right-to-left evaluation, rather than 17. Thus, the 
expression is interpreted as 



3x(4+5) 
27 

You can control the order in which individual functions are evaluated 
by enclosing part of the expression within parentheses. To cause the 
expression above to evaluate to 17, enter the following: 



(3x4) +5 
17 



APL evaluates this expression as 17 because 5 is added to the quantity 
3x4, not simply to 4. 
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2.2 Number Precision 

APL is a double-precision system with internal precision of about 18 
decimal digits. Numbers are represented internally in two ways. 

1. Integers less than 2 to the 35th power (2*35) are stored with 
full precision. 

2. Non- integers and integers larger than 2 to the 35th power are 
carried out in floating-point format. 

APL handles conversion between the two formats automatically. 

Although you cannot control the internal precision of numeric repre- 
sentation, you do have some control over the output representation. 
The DPP variable. Section 4.2.15, allows you to specify the output 
precision of non-integers. Also, the APL format functions ($ and t) 
can also be used to control the printing precision of specific numbers 
and arrays (Sections 3.4.5 and 3.4.6). 

Notice how APL outputs the numbers in these arrays: 



2 2fL/\0 
1 ♦70141. le^^e-^e 
1 ♦7014:1.1835^:30 



!♦ 70141 lB35in:38 
1^ 70141 183'ok:38 



«<-2 2ri 

A 




1 1 
i i 




a[:2J2:m-l/\o 




A 




l^OOOOOOOOOfi^O 
1 ♦ 0O00OO00Ok:0 


l^OOOOOOOOOKSO 
1 ♦701411835^:38 


*^^<"2 2^1 
Ai:i5 13MOA6 

A 




1000000 


1 


1 


1 


'^^<-2 2rl 

«i::2y2:]M0!«t"A 

A 




1 
1 


1 
0*000001 


'^=ti:if 1.1M0A6 

A 





1* 000000000^:6 
l»000000000is:0 



1* 0000000001^:0 
1^000000000ih:""6 
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The range of numbers you can input without receiving an error (15 

DOMAIN ERROR) are: 

For integers ~2*35 to (2*35) -1 

For non-integers . 14693679E-38 to 1.7014118E38 

Note that Boolean is represented as 36 bits per word: (136) =136 is 
equal to 36pl. 



2.3 ERROR HANDLING 

When APL encounters an error, it prints three things: 

1. an error message 

2. the line in which the error occurred 

3. a caret {^) approximately underneath the particular point at 
which the error was discovered 

The following are examples of common error conditions: 

11 VAL.UIH: ERROR 
AxB 



lMBf2f3 

7 SYNTAX ERROR 

in »f2 + 3 



1 2M 2 3 4 
10 l..k:hgth error 

1 2 f- 1 2 3 4 

A 

In the first example, APL printed a value error because the variable 
named A had not been assigned a value. The syntax error occurred 
because an identifier cannot begin with a number (15) . The length 
error was a result of an unequal number of constants on either side of 
the plus sign. 

Because APL is a highly interactive system, you can almost always 
respond to an error condition simply by correcting the statement in 
which the error occurred. This characteristic of the language also 
aids the trial-and-error approach to program development. In function- 
execution mode, APL prints an error message, the function name, and 
the line number of the statement at which it occurred. APL also sus- 
pends execution of the function. You then have the options of termin- 
ating the suspended function, restarting it possibly at another state- 
ment, or debugging it before resuming execution. Chapter 6 describes 
techniques for developing and executing functions. 

If certain types of errors occur in function-execution mode, you may 
not want APL to halt function execution to await your corrections. 
APL allows you to handle error conditions under program control. The 
execute functions c and i (Section 3.4.3) provide some control. How- 
ever, for more error-trapping facilities, refer to Section 6.5. 
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2 . 4 ARRAY INDEXING AND COMPARISONS - 

This section introduces the use of array indexing in APL and also the 
use of "fuzz" in performing comparisons. Both of these concepts are 
helpful in understanding the examples included in subsequent sections 
of this chapter. 



2.4.1 Indexing Arrays 

The concept of using and entering values for arrays has already been 
introduced in Section 2.1.2.2. To be able to access, individually, 
the values of the elements stored in an array, you must know the posi- 
tions of the elements within the array. These positions are known as 
the indices. The procedure for accessing elements is called indexing. 
The first position in an array (index origin) can be either or 1 . 
You can set the index origin with system variable UIO , Section 4.2.11. 

To index an array, specify the array followed by the indices enclosed 
in square brackets, and separated with a semicolon. Each index must 
be an integer scalar, or an expression that evaluates to an integer. 
The number of indices needed to pinpoint an element depends on the 
array type. In general, you must specify as many indices as the number 
of dimensions of the array. For a vector, a single index is sufficient 
to identify the position of the desired element. A matrix, a 2- 
dimensional array, requires two indices separated by semicolons; a 
3-dimensional array requires three indices separated by semicolons; 
and so forth. 

For example, specifying: 

accesses the first element stored in vector A. If A consists of the 
vector shown below, then /4C3] is 25. 

A<-72 91 25 46 87 

Ai::5:] 



If the array is a matrix, specify two indices: the first one for the 
row and the second one for the column: 



Bf. 


2 


Ar\S 


B 






> 


3 


A 


> 


7 


S 


»i: 


2? 


31 
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Specifying the indices in the form of an array enables you to access 
more than one element at a time. For example: 

Af-32 44,6 71 .80 65 97,2 



A 

32 44. A 71 0.8 65 97.2 

A|:3 5 6:j 
71 65 97.2 

Mf-2 4fl8 

M 

12 3 4 

5 6 7 8 

M|;2yl.l 
5 

Mi:i 2J2 3:1 

2 3 

6 7 

The index can also be an expression which is evaluated to generate the 
element positions. 

3:<-2 4 5 

VMO 22 31 49 56 68 72 
vci-flJ 
31 56 68 

Here V and I are both vectors. The expression 7[J] accesses the ele- 
ments of V referenced by J: that is, the third, fifth, and sixth 
members of vector V. 

Character arrays can also be indexed. For example: 

A<- ' ABCOEFGHI JKL.MHOpaRSTUVWXYZ » ' 

BABYfACio 5 14 14 9 6 5 18 27 12 25 14 27 13 28.T 

BABY 
■JENWIFER L.YN M, 

Note that an element can be duplicated by specifying its position more 
than once. The array being indexed need not be a variable. It can be 
a constant set of values or an expression enclosed in parentheses. 
For example: 

7 6 5 4 3 2 1[:2 4:;i 
6 4 

(2 4 8 16a2)i::i 2::i 

4 16 
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You can omit a subscript from an index specification, but the semi- 
colon must be included if only one array dimension is specified. If 
you omit the right subscript, all columns are selected from the matrix; 
if you omit the left subscript, all rows are selected. For example: 



1 


2 


3 


4 


5 


6 


7 


e 


9 


10 


11 


12 



«i:m 



12 3 





'^CJ2 


33 


2 


3 




5 


6 




8 


9 




11 


12 





Note that a semicolon is required to indicate which subscript has been 
omitted. In general, the size of the result when a variable is indexed 
is equal to the catenation of the sizes of all the indices. For ex- 
ample, if Z^Z[Jl;J2;I3; . . . JiV] then ( pZ ) = ( pJl ),( pJ2 ),( pi"3 ),...( pliV ) . 



vi:3 511 



CE 



n VECTOR- IHEiEMEri WITH rt VECTOR 
^RESULTS XW A VECTOR 

vi::6 5 4 3 2 111 

FEt'CBA 

flVECTOR IHDEXED WITH A MATRIX 
f^ RESULTS XH A MATRIX 

M<-2 3^2 5 4 6 S 4 



BED 
FED 



fl MATRIX INDEXEf WITH TWO 2" It-' ^ MENS I OHAI-. 

n INDICES Fi:ESUI.„TS Xii A 4....i;i I MEWS I ONAL. ARRAY 

M<-2 2fl 2 2 1 
a<-M|:mj m;] 

A 
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1 
1 

:l 
1 

2 6 



M<-2 4ri6 

M 

2 3 A 

f, SCALAR RESUUT 

A 

flfajL.L. ARRAY 
f A 

(^ I ■■■■ E U E M E N T V E C T O R S 

»2<M[:» 1 J 1.1 

B 

f>v.<2 



n2 EI-E^MEWT VECTOR 

c 

f) /:> 2 ^' T' 1. M A T R 1 X 
D 



(APL outputs a blank line] 



6 
2 1 



f.t. 



You can also use indexing to change values of elements already stored 
in an array. For example: 

Af-2 3r\6 



12 3 
4 5 6 

«r.;i;2 zn-v s 

''>i:2yl 23f-9 

A 

1 7 8 
9 9 6 
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A|::l?13M2 



12 7 a 

9 9 6 

Ai:i?i i:i<-2 3 

2 7 8 
9 9 6 

2.4.2 The Index Origin 

In APL, the first position of a value stored in an array is called the 
index origin. You have the option of beginning the indices of an array 
at either 1 or 0. For example, if the index origin is 1, then members 
of a vector named A would be numbered ALU, AT 22, AL32, and so forth. 
If the index origin is 0, elements begin at i4C0], ALU, Al2l, and so 
forth. 

The default index origin in a clear workspace is 1, but you can change 
this setting to or reset it to 1 with the UIO variable (Section 
4.2.11). The index origin setting is saved when you save your work- 
space. Refer to the ) SAVE command. Section 5.2.4. 

The value of the index origin is often used in conjunction with several 
monadic and dyadic functions. Chapter 3 discusses the index origin in 
that context. 



2.4.3 Comparison Tolerance or Fuzz 

APL handles the problem of performing decimal arithmetic on a binary 
machine with a concept known as fuzz. When two non-integer numbers 
are compared, for example, 7.913 and 8.019, they are considered equal 
if the difference between them is within a certain range. This range 
is referred to as the comparison tolerance or the fuzz quantity. 

There are two types of fuzz: 

1. Absolute fuzz - which is the tolerance used to determine 
whether or not a decimal number is close enough to an integer 
in value to be considered an integer. 

2. Relative fuzz - which is the tolerance used when comparing 
two numbers to determine whether or not they are close enough 
to be considered equal. 

The absolute fuzz in this version of APL is approximately 1E~7. This 
setting cannot be changed. The default relative fuzz is IE 13 in a 
clear workspace. You can change the relative fuzz in your active work- 
space by assigning a new value to the UCT variable. Section 4.2.7. 
The relative fuzz setting is saved when you save your active workspace, 

The following functions use UCT when making comparisons: <, <, -, >, 

>, ^, A\B, AeB, lA, AlB , [A, ALB. 
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2.5 TERMINAL I/O OPERATIONS 

APL provides you with utilities to ease input and output operations on 
a variety of system devices. This section describes terminal input 
and output. Chapter 7 describes the file system that APLSF uses to 
handle file-oriented I/O in ASCII sequential, internal sequential, 
direct-access, and binary-access format. 

There are several methods of input and output as illustrated by Table 
2-1. 



Table 2-1 
Input/Output Functions 



Expression 


Meaning 


Section 


A<-U 


Quad (evaluated) input 


2.5.1 


A^\n 


Quote-Quad (character) input 


2.5.2 


A^U 


Quad-Del (unedited) input 


2.5.3 


iiiWiii 


§§Kg§ll§MKiSSS^^^ 


7.2 


A 


Normal output 


2.5.5 


A;B;C 


Mixed output 


2.5.6 


U^A 


Quad output 


2.5.5 


\n^A 


Bare output (Quote-Quad) 


2.5.7 


U^A 


Bare output (Quad-Del) 


2.5.7 


iiii^lili 


|||||l|;g:|iu|;f«f^^ 


'7^2' 



All terminal I/O, except normal and mixed output, use the D symbol 
All forms of I/O can be used in either immediate mode or function- 
execution mode ^,_^^^|^ 

■§ift|i|^iiii|ii^i^Pii§lg|||p The following sections describe the basic 
forms of the quad function. 
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2.5.1 Evaluated Input Mode-Quad Input (D or .BX) 

The most basic form of quad input is called evaluated input. In this 
mode, the statement you enter at the terminal, in response to the D 
input request, is evaluated and its value is returned as the result of 
the D input function. By placing a D to the right of a back arrow in 
an expression, you signal APL to expect data input from the terminal. 
Normally, APL prompts you by printing D: in the left margin. You can 
change the prompt with the USF system variable (Section 4.2.18). Any 
character data input must be enclosed in single quotation marks. Other- 
wise, it will be considered an APL expression. For example: 



at 



a: 



10 



at 



i<<-a 



ft<-2xD 



MSGf-O 



' NO OPERATOR 



HO OF ERA TOR 



While the system is awaiting your input, you can enter and execute a 
system command, evaluate an expression, or define a function. The 
input request remains pending. If an error is encountered in the 
input, APL prints the appropriate message and allows you to reenter 
the input. If you enter a carriage return or spaces and a carriage 
return, APL again prints the D: prompt and waits for input. 

The prompt signal (D:) is the default. You can change it with the USF 
variable, Section 4.2.18. 



2.5.2 Character Input Mode-Quote-Quad (ffl or .QQ) 

APL has another version of the quad function especially for input of 
character data, the quote-quad function (Q) . An example of quote- 
quad mode is shown below: 

THAT'S AMAZING 

THAT ' s ama;-:::i:no 
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Unlike evaluated input, quote-quad input allows you to enter character 
strings without enclosing them in single quotation marks. Note that 
APL does not print the D: prompt in quote-quad mode. 

When APL encounters a n symbol, it positions the carriage at the left 
margin and accepts the data up to the next carriage return as a char- 
acter variable. If you enter a single character, APL treats it as a 
character scalar; it stores a string of characters as a character vec- 
tor. If you enter only a carriage return, APL treats this input as a 
vector of length zero; this treatment is significantly different from 
the handling of empty input in quad-input mode, in which APL rejects 
the input and waits for you to reenter it correctly. If you enter a 
tab, APL converts it into the equivalent number of spaces accomplished 
by the tab. 

Note that you cannot enter and execute system commands or define func- 
tion during [H input. 



2.5.3 Unedited Input Mode-Quad-Del (M or .QD) 

APL has a third version of the quad function, the quad-del function 
(S) . The quad-del function allows you to enter special characters, 
including backspace, without having APL evaluate them. The backspace 
is treated as a separate character, and an overstrike symbol is not 
created. 

APL counts each character you input in quad-del mode. The length of 
the expression includes any spaces and backspaces. (A tab is treated 
as one character.) The following example illustrates the difference 
between quad-del and quote-quad modes in entering overstruck APL char- 
acters. The example uses the transpose function (^) which takes an 
array and transposes its values (Section 3.3.20). To input this func- 
tion, type o, press BACKSPACE, and type \. The result of the shape 
function (p), (Section 3.3.18), prints the number of characters in the 
array. 



A 



f, T H E B A C K S P fA C B 1 S C O U )■( T I:." D fi, S f^t C H fA R A C T' Ei! R » 

■•'•m:i 

fi :i: H a o u T K." •••• « u A i:> , r i-i i;;: b (■> c k s p^- (-^ c i;;; i s n a r c o u ii r b: i." , 
p.x 

f^XH sxi(GL.B «uote;:Sj, :i:"r xs not count ex:' either, 

f ' fijA ' 
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The following example shows the particular use of quad-del mode in 
accepting input from non-APL-keyboard terminals. The mnemonics are 
not decoded. 

A...,QD 

♦ ROB 

♦ ROA 
4 

A...»a« 

♦ ROB 

♦ ROA 

♦RO' ♦ROB' 



As in quote-quad input mode, if you enter only a carriage return or 
spaces followed by a carriage return, APL treats this input as a null 
vector of length zero. 



2.5.4 Escaping From Input Mode 

To escape from an input request, you have certain escape options de- 
pending on the input mode: 

In quad-input mode, type a right arrow (^) 

In quote-quad (Q) or quad-del (M) input mode, type OUT as 
follows: 

backspace U backspace T 

or 

On non-APL-keyboard terminals, type .OU 

Each of these methods causes function execution to be interrupted but 
does not cause an exit from the function. Refer to Chapter 6 for 
information on function-execution mode. 



2.5.5 Normal and Quad Output Modes 

In normal output mode, to display output on the terminal, type an 
expression or an identifier without an assignment function (-«-) or 
branch function (^-) as the leftmost character. The result of the 
expression prints on the terminal. For example: 

64*3 
262.144 

17tA 

42 
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If the quad symbol appears immediately to the left of an assignment 
function (-<-) , the result of the expression to the right of the -^ 
prints on the terminal. This is called quad output. For example: 

Of. A 



Note that using quad output has the same effect as in the previous 
example of merely typing the variable name A. Quad output is espe- 
cially helpful when an APL statement contains multiple assignments. 
For example: 

20 



This statement performs the computation and displays the desired out- 
put - the result of the computation 5x4. This method is more efficient 
than the following: 



20 



B<-5x4 



If the last operation (the leftmost expression) in an expression is an 
assignment or branch, then no final output is produced. The following 
will not cause output to be printed : 

Af.5>!4 

The following will: 
4 lAfS 



When APL outputs an array, and a row cannot fit on a single line, the 

remainder of the line prints on the following line, indented six 
spaces. For example: 

12 3 4 5 6 7 8 9 :l.O 1:1. :l.2 :l.3 :l.4 :l.5 16 17 10 19 

20 21 22 23 24 25 26 27 28 2? 30 31 32 33 

34 35 36 37 38 39 40 41 42 43 44 45 46 47 
48 49 50 



To provide more room on a line you can alter the page width with the 
UPW system variable. Refer to Section 4.2.16 for this information. 
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2.5.6 Mixed Output Mode 

Mixed output mode allows you to print character data and numeric data 
on the same line. You request mixed output by entering a series of 
values or expressions, separated by semicolons, in the order in which 
they are to appear. The output displayed contains no carriage returns 
or spaces, except where required by the data. 

Although APL evaluates from right to left, it prints items from left 
to right. If you display two expressions separated by a semicolon, 
APL will not put a space between them. You must specify a space if 
you want one. For example: 

24 

l.»:l y ' ' y2*-2 
2 4 



In the first part of the next example, APL reports a value error 
because no value is assigned to B . In the second part, B is assigned 
the value first. 

:|. ], VAI._Ulfi: ERROR 

A 
t-fB?' 'JBM 

2 :l. 



APL will not print a value if the leftmost expression on a line is an 
assignment or branch operation. You can get around this by enclosing 
the assignment within parentheses. Note the following examples: 

' THE VAI...UE OF A X.S 25' 
THE VALUE OF A XS 25 

Af'3p ' noth:i:ncv wi:i.,.i... I"R:i:nt XvtE cause of the arrow' 

(Af. 'THIS ' ) J ' w:i:l..i... pr:i:nt because of the parentheses' 

THIS WIL.I... PRINT BECAUSE OF THE PARENTHESES 



Another way of printing the leftmost expression containing an assign- 
ment or branch, is to precede the statement with a semicolon: 



Bf.5 



2-21 



LANGUAGE SYNTAX 



Although the semicolon is considered a statement separator, each ex- 
pression in the list must return a value. For example, if F is a user- 
defined function that does not return an explicit result (regardless 
of the number of arguments F requires), the construct ';F;' returns 

an 11 VALUE ERROR. 



\"2"\ ' h:i: there 

I": 3 :;i ^^ 

:l. y f' 5 2 

HX THERE 
HX THERE 

■_\ X VALUE ERP::OR 
:l. y l^=- y 2 



2.5.7 Bare Output Mode (Quote-Quad B or Quad-Del E) 

Bare output is a special mode that allows you to request input on the 
same line as an output string. 

Like quad output mode, if you place a quote-quad or a quad-del to the 
left of an assignment function, the expression to the right of the 
function prints on the terminal. However, unlike quad output, APL 
does not perform a carriage return/line feed at the end of the output, 
Note the difference in the following example: 

^■^ <•• n y r.:i < • k-- >-i t ^ <■■■ if (•■) t-.' i-': ii f-^ m hi: • 

ENTER YOUR NAME 
XRENE 

A 
XRENE 



Notice that the value input is preceded by a number of spaces equal to 
the length of the M output. 

If the last character of a character constant to be output is a 
comment (lamp) character fl, APL suppresses the printing of the a as 
well as the usual delimiting carriage return/line feed, thus, leaving 
the carriage in mid-line. This feature is useful for entering input 
on the same line as the previous output. For example: 

Af 1^1 J |;|f ' ENTER YOUR NAME n' 
ENTER YOUR NAME PrOSE 

ROiiiE 



In immediate mode, bare output is the same as normal output. A bare 
output statement such as IH-^A must be followed by an input entry at 
the terminal. Thus, in this instance, output is concluded by the 
conventional carriage return/line feed. Bare output is more appro- 
priate in function-execution mode. Refer to Chapter 6 for more infor- 
mation on functions. 
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3 . 1 INTRODUCTION 

APL provides several characters, known as functions and operators, 
that allow you to perform various operations with numeric data and 
character data. These functions and operators are grouped as follows 
within this chapter: 

1. Primitive Scalar functions - arithmetic, relational, and 
logical, Section 3.2 

2. Primitive Mixed functions - for extensive array manipulation. 
Section 3 . 3 



3. Extended functions - for more advanced data formatting. 
Section 3.4 

4. Operators - more than one function in the syntax, Section 3.5 

Functions are either monadic or dyadic. A monadic function requires 
only one argument placed immediately to the right of it. A dyadic 
operator requires two arguments, with the function placed between 
them. Depending on the function, arguments can be variables, numbers, 
character strings, or expressions. 

Functions are also classified as either scalar or mixed. A scalar 
function generally takes a single-value argument and returns a single- 
value result. However, scalar functions can also be used with vectors 
and arrays where they operate on an element-by-element basis. A mixed 
function can take a scalar argument and return a result in the form of 
a vector or an array, or take a vector or array argument and return a 
scalar result. Therefore, the result of a mixed function is not as 
apparent as a scalar function. 

Both scalar and mixed functions can be either monadic or dyadic. With 
a scalar monadic function, the shape of the argument determines the 
shape of the result. For example, a scalar argument returns a scalar 
result; a vector argument returns a vector result, and so forth. When 
using scalar dyadic functions, you must specify arguments that have 
the same number of elements and, if arrays, the same dimensions. 
Table 3-1 shows the results achieved by specifying certain arguments 
to scalar dyadic functions. 

An operator is a function that takes another function as its argument. 
APL operators are described in Section 3.5. 
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Table 3-1 
Results of Scalar Dyadic Functions 



Argument 


Function 


Argument 


Result 


scalar 


f 


scalar 


scalar 


scalar 


f 


vector 


vector 


vector 


f 


scalar 


vector 


vector 


f 


vector 


vector 


scalar 


f 


matrix 


matrix 


matrix 


f 


scalar 


matrix 


matrix 


f 


matrix 


matrix 



3.2 PRIMITIVE SCALAR FUNCTIONS 



The primitive scalar functions are the arithmetic, relational, and 
logical functions. They are used primarily for basic arithmetic and 
logical operations, such as addition, exponentiation, maximum value, 
and logical OR. With a few exceptions, primitive scalar functions 
take numeric scalar arguments. The relational functions {<,>,<,>,=,*) 
can take either character or numeric arguments but only the equal (=) 
and the not equal (^t) primitives can take both character and numeric 
arguments in the same expression. The logical functions (a , v ,~,9V,v) 
must have arguments that are equal to or 1 within a tolerance of 
1E~7 , the absolute comparison tolerance that APL uses (Section 2.4.3) 

Table 3-2 summarizes the primitive scalar functions available in this 
version of APL. Most of the functions are straightforward and familiar 
arithmetic or logical operations. 
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Table 3-2 
Primitive Scalar Functions 





Monadic 




Dyadic 


Function 


Meaning 


Function 


Meaning 


+y 


7 


X+Y 


Add Z to 7 


"J 


Negative of Y 


X-Y 


Subtract 7 from X 


xj 


Sign of Y^ 


XxY 


Multiply X and 7 


vY 


Reciprocal of Y 


X^Y 


Divide X hY Y 


*7 


E to the Yth power 


X*Y 


X to the 7th power 


i:^ 


Magnitude of Y 


X\Y 


X residue of 7 (see 
primitive mixed 
operators) 


\Y 


Ceiling of Y 


X[Y 


Maximum of X and 7 


II 


Floor of Y 


XlY 


Minimum of X and 7 


®y 


Natural logarithm of Y 


X9Y 


Log of 7 to the 
base X 


\Y 


Factorial of Y 


XlY 


Binomial coeffici- 
ent (number of 
combinations of 7 
things taken X at 
a time) 


?Y 


A random integer of \Y 


XlY 


X number of random 
integers in the 
range 1 through 7 


OY 


Pi times Y 


XOY 


Trigonometric 
functions (7 is in 
radians. See Table 
3-3) 



^Definition: x7 is -1 if 7<0 
x7 is if 7=0 
x7 is 1 if 7>0 



3-3 



APL FUNCTIONS AND OPERATORS 



Table 3-3 lists the values through 7 and through -7 that are 
needed as the left argument to the circle function (o) in order to 
perform trigonometric functions. The right argument, a scalar or 
vector, is expressed in radians. 



Table 3-3 
The Dyadic Circle Function 



Expression 


Result 


Expression 


Result 


ooz 


(1-J*2 )*. 5 






loZ 


sine X 


-lOZ 


arcsin X 


20Z 


cosine X 


-20J 


arccos X 


SOX 


tangent X 


-30Z 


arctan X 


40Z 


(1+J*2)*. 5 


-40J 


(-1+Z*2)*.5 


5 0Z 


sinh X 


-box 


arcsinh X 


60X 


cosh X 


-60Z 


arccosh X 


lOX 


tanh X 


-lox 


arctanh X 



The following examples illustrate ways in which primitive scalar 
functions can be extended to arrays: 



A<-3 3r5 A B 3 2 1 6 4 2 



5 6 8 
3 2 :l. 

6 A 2 



Pt b: I... E M E H r ■■■■ B r ■■ K-: I., fi:: m e: w r- m u i... i' .i: f- l. x. a f^ r x o h 

AxA 



2S 


36 


64 


9 


4 


1 


36 


16 

2 X A 


4 


10 


12 


16 


6 


4 


2 


12 


9 


4 



2*0 12 3 4 5 6 7 8 
12 4 8 16 32 64 128 256 

4 9 16 25 36*0,5 
2 3 4 5 6 
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3.2.1 Relational Functions 

In APL, the relational functions (^,>,<,>, = ,?i) return results; they 
are not simply comparison functions. An expression of the form A<B 
yields the result of 1 if true (.4 is less than or equal to B) , and 
if false. For example: 

9>6 



A>6 



' c ' > ' A ' 



These functions can take either numeric or character arguments, but 
only the equal and not equal functions can have mismatched arguments, 
that is, one numeric and one character argument simultaneously. For 
example : 



When you use relational functions with Boolean arguments (0 and 1) , 
the relational functions can perform logical operations. For example, 
the not equal (^) function performs an exclusive OR operation if its 
arguments are Os and Is: 

0/0P0/.1. y:l.i^0y:l.y^1. 

001..1.i^0:l.0l 
1 
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3.2.2 Logical Functions 

The following table is a truth table that describes the results of 
logical operations: 

Table 3-4 
Truth Table 



Argument 


s 






Functions 








AND 


OR 


NAND 


NOR 


X 


Y 


XaY 


XvY 


X^Y 


ZV7 














1 


1 





1 





1 


1 





1 








1 


1 





1 


1 


1 


1 












NOT 








X 




~Z 













1 








1 
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3.2.3 I or .AB ~ The Residue Function 



Format 



dyadic 
Argument Types 



Both arguments can be either scalars or vectors and either 
integer or noninteger. 



Definition 



Obtains the remainder or residue of a number. The residue is a 
unique number whose value is in the range between the value of 
the left argument and zero. It is obtained by adding or sub- 
tracting multiples of the left argument from the right argument, 
For example, for positive arguments / the remainder is obtained 
by dividing right arguments from left arguments. The result of 
a residue operation has the same sign as the sign of the left 
argument . 

The formal definition of the residue function is as follows: 



A \B IS B->lxLBv 4+^ = 



If the left and right arguments are equal, the residue is 0. If 
the left argument is 0, then the residue is equal to the value of 
the right argument. 

If the left argument is not 0, then the residue is in the range 
of the left argument through ; it may equal but not equal the 
value of the left argument. 
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Examples 





7 

:l , B 
3 3 



518 
■■517 
717 
710 
I 7 
2 I 5 » 8 
5 518 8 



,j ».i »j 



> ':> ':> 

,::■ , ,.) ,;) ,., 



':> '■> '•> 



Related Functions 
None 
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3.2.4 7 - The Roll Function 
Format 

monadic 
Argument Types 

The argument is an array of positive integers. 

Definition 

Generates an array of independent random integers. Each element 
is in the range or 1 (depending on \M0) to the value of the 
corresponding element in the argument. There may be duplicate 
values. Roll also changes {IRL. See Section 4.2.17. 

The term "roll" relates to the analogy between the operation 
performed by this function and the rolling of several dice. 

Examples 



?5 :l.O ;l.5 20 25 

2 6 2 ;l.4 8 

?S :l.0 15 20 25 

5 6 13 2 21 





A<-2 


3/M6 




<>\ 




1 


2 3 




4 
1 


5 6 
2 3 




2 
1 


5 4 

'i>A 

2 2 




4 
1 


2 6 
1 2 




J. 
3 


3 4 





Related Functions 

Deal, Section 3.3.3 

Deal differs from roll in that deal generates a set of random 
numbers in which no number is selected twice. 
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3.3 PRIMITIVE MIXED FUNCTIONS 

Unlike the primitive scalar functions discussed in the previous 
sections, the functions presented in the following sections are 
considered primitive mixed functions. Scalar functions usually take 
scalar arguments, return scalar results, and are extended to arrays 
on an element-by-element basis. Primitive mixed functions, however, 
can take vector arguments and return scalar or vector results, or can 
take scalar arguments and return vector results. In expressing primi- 
tive mixed functions for arrays of higher rank, you may need to speci- 
fy the particular coordinate of the array to which the function applies 

The primitive mixed functions provide the capability of extensive 
array manipulation. 

Table 3-5 lists the primitive mixed functions available in this 
version of APL. The operators are also listed. 



Table 3-5 
Primitive Mixed Functions 



Function 


Section 


Meaning 




X,Y 


3.3.1 


Catenate Z to 7 along the last dimension of 

X 


X/Y 


3.3.2 


X (logical) compression along the 
dimension of Y 


last 


X/INIY 


3.3.2 


X (logical) compression along the 
dimension of Y 


ilfth 


XiY 


3.3.2 


X (logical) compression along the 
dimension of Y 


first 


X?Y 


3.3.3 


Deal X integers selected randomly 
1 through Y without duplication 


in range 


XlY 


3.3.4 


Decode the representation of Y in 
system X 


number 


X^Y 


3.3.5 


For X>Q , drop first X elements of 
X<Q , drop last \X elements of Y 


Y - for 


XjY 


3.3.6 


Encode Y in number system X 




X\Y 


3.3.7 


X (logical) expansion along the last 
dimension Y 


X\lN'}Y 


3.3.7 


X (logical) expansion along the il/th 
dimension of Y 


X\Y 


3.3.7 


X (logical) expansion along the first 
dimension of Y 


Jt7 


3.3.8 


Generate an index vector such that Xl^Y~\ 
is in descending order 
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Table 3-5 (Cont.) 
Primitive Mixed Functions 



Function 


Section 


Meaning 


XkY 


3.3.9 


Generate an index vector such that ZCiY] 
is in ascending order 


\Y 


3.3.10 


Generate the first Y consecutive integers 
from current origin 


XxY 


3.3.11 


Find the first occurrence of Y in vector X 


X.LNIY 


3.3.12 


Laminate J to 7 along the Nth dimension of 

X 


XeY 


3.3.13 


Determine the membership of X in array 7 


,Y 


3.3.14 


Return the ravel of 7 (make 7 a vector) 


4)7 


3.3.16 


Reverse along the last dimension of 7 


(^LNIY 


3.3.16 


Reverse along the il^th dimension of 7 


BY 


3.3.16 


Reverse along the first dimension of 7 


pX 


3.3.18 


Return the shape of X 


XpY 


3.3.15 


Reshape 7 to make dimension X 


X<^Y 


3.3.16 


Rotate by X along the last dimension of X 


X<^LN1Y 


3.3.16 


Rotate by X along the Nth dimension of 7 


XeY 


3.3.16 


Rotate by X along the first dimension of 7 


XiY 


3.3.19 


For X>0*, take first X elements of 7 - for 
X<0, take last ]X elements of 7 


<s?7 


3.3.20 


Transpose the dimensions of 7 (for a 
matrix, exchange the rows and columns) 


j<s?y 


3.3.21 


Transpose array 7 according to X 
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3 .3.1 , - The Catenate Function 

Format 

dyadic 

Argument Types 

scalar s, vectors, or arrays 

Both arguments can be either numeric or character data. 

Definition 

Chains two scalar or vectors to form a new vector. Catenation 
joins constants or variables along an existing dimension. Any 
number of items can be catenated. The order in which values are 
catenated is the order in which you specify them in the APL 
statement. Actually, the value (s) of the argument to the right 
of the catenate function is appended to the value (s) of the 
argument to the left of the function. 

The result of a catenation can be formally expressed as follows: 

if pA is 5 and p5 is 3, then pB-(-A,B is 8, i?[i5] is .4 and i?[5+i3] 
is B. 

You can also catenate literals. APL does not allow you to 
catenate numbers to characters and vice versa. If you attempt 
this, you will receive a 15 DOMAIN ERROR. 

The catenate function also allows you to join multidimensional 
arrays along an existing coordinate as long as they have the same 
length over the other dimensions. You include the coordinate 
within square brackets along with the right argument of the 
catenate specification. For example, A,ll^B. The coordinate is 
1 for first dimension (row) , 2 for second dimension (column) , and 
so forth. 

You can also catenate constants to an array or matrix. If you do 
not specify the coordinate, APL assumes the highest rank of the 
array being catenated, that is, the last dimension. See examples, 

When catenating arrays, you must follow two general rules: 

1. Using the expression A,LK1B, if the arrays have equal rank 
((pp^)=ppB), then K must be in ipp^l and pA must equal pB 
except in the Kth dimension. This is illustrated in the 
following: 



3 4 5 
3 6 5 

3 10 5 



R i- ft y i;; 2 :;i B 



Here A is equal to i?[;iM-;] and B to i?[;M-+x6;]. 
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2. If the arrays have different rank ((ppA)^ppB) then one of the 
arguments must be a scalar (1=\ (pQA)-ppB) , and pB must equal 
p^ without its i^th coordinate. This is shown below: 

f A 

3 4 S 

4 5 

f Hi: 
4 4 S 



Here, A is equal to i?[i3;;] and B to i?[4;;] 



Examples 



The following example catenates two vectors to each other and to 
several scalar values: 

Bi-7 s 

A f B 

5 8 9 7 8 

10 5 8 9 7 8 :l,2 

■ NAME ' f > MY • 
HAMHXY 

A<!-2 3Fi 2 3 A 5 6 

^i-2 3f7 8 9 :i.o ;u. :l,2 

1 2 3 
4 5 6 



B 

8 



:lo 



« y t: 1 :;i i^- 

;i. 2 3 

4 s 6 

7 8 9 

1 1 1 1 2 

Ayi;:2:;iB 

;l. 2 3 7 8 9 

4 5 6 :l.O :l.:l. 12 
-"•^y i;:i;:i7 

12 3 
4 5 6 
7 7 7 
Ay 7 
12 3 7 
4 5 6 7 
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X4..2 


3re 7 3 9 4 




'''<■■ 2 


3r0 12 3 4 




■< y [: :l 


. ::i T- 


8 


7 3 




9 


4 {:} 







:l. 2 





4 



3 
8 3 



Related Functions 

Laminate/ Section 3.3.12 
Ravel, Section 3.3.14 
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3.3.2 / and / - The Compression Function 

Format 

dyadic 

Argument Types 

The right argument can be a scalar or any array. The left 
argument must be the scalar argument or 1 , or a Boolean vector 
(a vector containing only Os and Is) . 

Definition 

Builds a new vector or array from an old one by specifying the 
elements to be deleted and the elements to be preserved. For 
example : 

A^ 5 7 9 11 13 
BM 1 1 



Elements in A whose positions correspond to the positions of 
nonzero elements of B are preserved; elements corresponding to 
zeros in B are dropped. If B contains only Is, all elements of 
A are preserved; if B contains only Os, the result is an empty 
vector. 

The lengths of both arguments, for example A and B, must generally 
be the same. However, if A is of length 1, it will automatically 
be extended to the length of B; if B is of length 1, it will be 
extended to the length of A . Thus : 





Af-S 


7 


9 


11 




13 




BfX 


1 





1 







S 5 


B/5 














l/« 












7 9 


1 1 


13 











0/A 



(APL outputs a blank line) 



The expression 0/^4 produces an empty vector because all elements 
of ^ are dropped. 

You can also compress arrays by specifying, within square brackets, 
the coordinate to be compressed. (The coordinate is dependent 
upon the index origin. Section 4.2.11.) For a matrix, compres- 
sion along the first coordinate can cause certain rows to be 
omitted; compression along the second coordinate can cause columns 
to be dropped. The result in all cases is a matrix. 



3-15 



APL FUNCTIONS AND OPERATORS 



If you omit the coordinate in square brackets, APL compresses the 
highest-ranking coordinate of the array. By specifying the 
special compression symbol / (.CS) without including a coordinate, 
APL compresses the first coordinate. 



Examples 



Af-3 4f\:l.2 

12 3 4 
•5678 

9 1.0 :l. :l. :l.2 

:i. 2 3 4 
9 :i.o 1. :i. 1.2 
1 1. o/i::2;;i« 

1 3 

5 7 

9 1. :l 

f (O/A) 



3 



>'i-2 3/MA 



12 3 

4 5 6 

1 1 
2 3 

5 6 

1 0/'< 
1 2 3 



Related Functions 

Expansion, Section 3.3.7 
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3.3.3 7 - The Deal Function 

Format 

dyadic 

Argument Types 

Both arguments must be positive scalars or single-element vectors 

Definition 

Generates a vector of integers randomly selected from the right 
argument vector without selecting any number more than once. 

The length of the vector produced by the operation is specified 
by the left argument. You can set the seed of the pseudo- 
random-number generator with the MRL system variable. Section 
4.2.17. Everytime you use the deal function, 7 , you change UB.L . 



Examples 



5?5 
13 5 2 4 

65950S3 65:1.4970 582465A 4389382 7540976 

5?1,0k;:7 
20:1.0075 94443:1.2 5995397 3627744 3545552 

5?1 *0i:^7 
5923563 42577:1.0 63238:1.4 5360300 2709926 



Related Functions 

Roll, Section 3.2.3 



Unlike the roll function, deal is like dealing a number of cards 
from a deck with no two cards alike. Roll is like rolling 
several dice independently. Roll may generate duplicates but 
deal will not. 
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3.3.4 1 or .DE - The Decode Function 

Format 

dyadic 

Argument Types 

scalars, vectors, or arrays 

Definition 

Reduces a representation in a number system to a value. It is 
the converse of the encode function (t) ; equivalent examples of 
the two functions as they operate on a quantity expressed in 
yards, feet, and inches, are shown below: 

1760 3 12t63 
:l. 2 3 

1760 3 12.i.l 2 3 
63 



The expressions AiB and AlB differ only in the value included in 
S; A expresses the number base in both cases. 

The number of elements in both arguments, for example A and B, 
must generally be the same; the first element in A expresses the 
base in which the first element in B is decoded, and so on. 
However, if .4 is a scalar or a single-element array, it is 
extended so that its length is the same as that of B. For 
example, the following expression has the effect of producing the 
base 10 value of the base 8 number 3777 (octal to decimal 
conversion) . 

8x3 7 7 7 
2047 



You can also specify the decode function with multidimensional 
arrays. The expression AlB is equal to W+ .XB where W is the 
weighting vector given by the expression {7[py4] 1 and f/[ ( -/li^) + p/4] 
is equal to /4C ( -/l/) + lp^]x(v/[ ( -/l?) + l + pyl] . The value of All'\ is 
irrelevant. 

The arrays you specify as arguments must conform to the following 
rules using A and B as arguments: 

1. i4 or B is a scalar. 

2. The results of -I^qA and IfpS are equal. 

3. Either I^qA or l^pB equals 1. 
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Examples 



flCOf-ivi:;:Hi:is 3 rfs ^ '?. f""<\ A :i:ncmes to :i:HCHi:i:s 

1 3 12 .L 3 2 A 
136 

fl-'--^ 2«S (-^ ZERO OF THii;: i"oi...ynom:i:ai... 6>'*2 -^'^ -20 
2»5.ji.6 ""7 "^O 


flBASE-J. E«u:i: VAL.ENT OF BASKi: .••;5 NUMBER 

5x4 3 A 
119 



Related Functions 

Encode, Section 3.3.6 

Inner Product, Section 3.4.1 

The decode function can be viewed as a form of the inner product 
operator. The following example illustrates two equivalent 
operations: 

«M760 3 12 
BM 2 3 
A . B 



63 



63 



36 12 l*-.xB 
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3.3.5 -t' or .DA - The Drop Function 

Format 

dyadic 

Argument Types 

The right argument must be an array. In most cases, the left 
argument must be a scalar; it can be a vector if the right 
argument is a multidimensional array. 

Definition 

Builds a new vector or array by dropping a specified number of 
elements from an existing array. For example: 

:i. 2 3 4 5 

p...:.:,..2iV 



The expression drops the first two elements of V and forms a new 
vector with the remaining elements. If the value of the scalar 
is greater than the number of elements in V, then the result is 
the null vector. 

The drop function handles negative scalar values by dropping the 
elements from the end of the array instead of from the beginning. 
For example: 

■■24^15 



You can also specify multidimensional arrays with the drop func- 
tion. In this case, the left argument must be a vector contain- 
ing one element for each dimension of the array. In the 
expression, S^V, the value of SLll indicates the number of 
elements to be dropped along the first coordinate of V, and so 
on. 
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Examples 





[;m-«<-3 5 


r\:LS 




:l. 


2 3 


4 


'5 


6 


7 8 


9 


:i.o 


.1 .1. 


:l. 2 :l. 3 


14 


15 


A 


S 






9 


.1.0 

:l. 3vi-« 






? 


:l.O 







14 1 ^ 



Related Functions 

Take, Section 3.3.19 
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The Encode Function 



Format 

dyadic 

Argiiment Types 



The right argument identifies the scalar or array to be trans- 
lated. The left argument is a vector that represents the number 
base in which the value is to be expressed. The vector contains 
one element for each column representation. 



Definition 



Represents a scalar or an array in any number system. For 
example, to encode the decimal value 7 in four columns of binary 
representation, the following expression can be specified: 



J. 1 :l. 

You can also specify mixed bases for the number to be represented. 
The encode function can express some number of inches in miles, 
yards, feet, and inches; or some number of milliseconds in days, 
hours, minutes, seconds, and milliseconds. The following examples 
illustrate these two situations: 



n M :i: i... i-i: ■:;; ,, r f>i [■■: t< s y f i:;: ifi: r , :i: > ■< c n e s 

1760 3 :I.2t273:I.25 
4 54A 2 5 

ft jC' f>i Y s y i-i o tj Pi: s y M :r: ti i.i r lii: <;; , s i;;: c o n r> s , m :i: l. i„ x s e: c o ii i:< s 

24 60 60 J. 000t7 19732523 
8 7 55 32 523 

In the expression AtB , A can be considered as the representation 
rule to be applied by B. Each element of the vector A is defined 
in terms of the element immediately to its left. Thus, in 
encoding a number as miles, yards, feet, and inches, the follow- 
ing elements are specified from right to left: 

1. 12 inches in 1 foot 

2 . 3 feet in 1 yard 

3. 1760 yards in 1 mile 

In the previous example, a miles specification is not defined in 
terms of another quantity, so is printed in the miles column. 
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The following examples of base 3 conversions demonstrate the 
specification of different numbers of columns in the rule vector 
and illustrate the way in which negative numbers are encoded: 



12 2 



3 3 3x17 
3 3x17 

3 3 3t"':I.7 



:l. .1. 



Another useful application of encode is to return the integer and 
fractional portions of a number: 

>^<-823<. 75:1.3 

:i.tJ' 

823 0.7513 

You can also specify the encode function with multidimensional 
arrays. The shape of the result of the expression R<-AtB is 
always ( pi4 ) , pS. 



Examples 



i;;H-«<i-»)3 2f2 3 



2 3 
2 3 



3 3 3 

»^5 2 

1 
1 
1 



f A 



865 429 
103 692 
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.10 .1.0 :I.OtC 
4 



3 



2 2 2 2 2t13 

1 :l. 1 

2 2 2 2 2t"'1.3 

:l. :l. :l. 



Related Functions 

Decode , Section 3.3.4 
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3.3.7 \ and \ - The Expansion Function 

Format 

dyadic 

Argument Types 

The right argument can be any array. The left argument must be a 
scalar value or 1 or a Boolean vector, a vector containing only 
Os and Is. If the right argument is a character vector, spaces 
are used instead of Os. The number of Is in the Boolean vector 
must generally be the same as the number of values in the array 
included as the right argument. 

Definition 

Builds a new vector or array by expanding the elements of another 
vector into a new format specified by the function. For example: 





f^i-\ 2 


? 




V\A 




1 2 3 






V\ ' API.. 


. ' 


f^ F=- 1 







The function expands the elements of A into the format specified 
by V. The values of A are inserted in positions corresponding to 
the occurrences of Is in V, For numeric values, zeros are 
inserted in positions corresponding to Os in the Boolean vector. 
If the right argument is a character string, as in the second 
example above, spaces are used instead of zeros. 

A scalar Boolean value as the right argument is extended as in 
the following example: 

:l. J.\5 



You can also expand multidimensional arrays along a particular 
coordinate. (The coordinate is dependent upon the index origin. 
Section 4.2.11.) You include the coordinate within square 
brackets. The syntax is the same as the compression function. 
Section 3.3.2. If you omit the coordinate, APL expands along the 
last coordinate of the array. To specify expansion along the 
first coordinate, use the special symbol \, or type .CB. 
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Examples 



tHAf2 3F\6 

12 3 

A 5 6 

J. 2 3 



4 S 6 

1 I i.\i::2:;iA 

10 2 3 

4 ::> 6 







0\U) 



Of-AfO 0\ 



(APL outputs a blank line) 



ATH:r<!>:i:i:>AN 
EXPANSION 
KTXAMF^I.-EA * 



3 9 



Vfl 1 1 1 1 1 1 1 
v\x 

A THIS :i:s AN 
EX I"- AN s:i: Oil 

EX AMP I...E Aft 

1 1 1\'< 
)irTH:i:s;i:sAN 

EXPANS:i:ON 
EXAMPLE A A 



Related Functions 

Compression, Section 3.3.2 
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3.3.8 t or .GD - The Grade Down Function 

Format 

monadic 

Argument Types 

The argument can be a vector or a matrix. 

Definition 

Creates an index to sort a vector or matrix in descending order. 
The t function creates a permutation vector that APL can use to 
sort the original vector. Duplicate values are ordered by their 
relative positions in the original vector. You can also reorder 
character arrays with t. The grade down function does not use 
fuzz in performing comparisons. 

The symbol 1/ is formed by over striking the del (V) with the 
residue ( 1 ) . 

Examples 

A<-2 9 7 4 3 :l.0 3 
6 2 Z A 5 7 1 

Ai::it:';.i 

10 9 7 A 3 3 2 

UHMI...AA 



Related Functions 

Grade Up, Section 3.3.9 
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3.3.9 i or .GU - The Grade Up Function 

Format 

monadic 

Argument Types 

The argument can be a vector or a matrix. 

Definition 

Creates an index to sort a vector or matrix in ascending order. 
If two or more elements of a vector or matrix have the same 
value, the order of the elements is determined by their relative 
positions in the original array. (Fuzz is not used in comparing 
the elements.) 

The i symbol is formed by over striking the delta (A) with the 
residue ( 1 ) . 

Grade up does not actually sort the vector. It creates a per- 
mutation vector of the index numbers of the elements. This vector 
is then used to sort the original vector. 

If the array to be sorted is a matrix, the simplest operations 
cause each row of the matrix to be treated as a string. The 
result of the grade up operation is a vector whose length is 
equal to the number of rows in the matrix. 

You can cause a matrix to be sorted by rows; and by subscripting 
the function, you can also sort on the basis of columns. For 
matrices, the expression kM is equal to i[2]M. 



Examples 





Af-2 9 7 4 


3 


10 


3 




0<B<..4,A 








15 7 


4 3 2 6 








2 3 3 


4 7 9 .1.0 

A 








ihtevk: 










SAM 










STAN 


f A 








3 '5 


4»A 








2 3 1. 


A|:iAp3 








SAM 










STAN 










STEVE 
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» 






3 


2 1 


5 





3 


1 9 


7 





3 


2 


B 





3 S 


^B 






2 3 


1 








»i::.*B 


? :;i 




3 


:i. 9 


7 





3 


2 


8 





3 


2 1 


5 






Related Functions 

Grade Down, Section 3.3. 
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3.3.10 1 or . 10 - The Index Generator Function 

Format 

monadic 

Argument Types 

The argument can be a nonnegative integer scalar or a 1-element 
array. 

Definition 

Generates a number of consecutive integers equal to the value 
specified as the argument, starting from the value of the index 
origin. Section 2.4.2. 

The expression \N generates a vector containing N components. If 
the index origin is set to 1, these components have values 1 
through N. If the index origin is set to 0, then the resulting 
vector has values through N^l. 

The index origin default is 1 in a clear workspace, but this 
setting can be changed with the ) ORIGIN command (Section 5.5.4) 
or the UIO variable (Section 4.2.11). 

Examples 

n<-Af. ,4 

:l. 2 3 4 

!■- f-y 

A 

ft POWERS OF 2 

2 A \ ;|. 2 
2 4 8 :l.6 32 64 1.28 256 5:1.2 :l.024 2048 4096 

ft OF TEN USED WITH RHO 
f (50 
50 

'<i-? 1 3 4 

12 3 4 

ft cj k:: ti i:;: i-: a r k;: s a ii u i... i.. v k;: c r a i">: 

1.0 

(APL outputs a blank line) 

f \ 



Related Functions 

Index of Section 3.3.11. 

Reshape and Shape, Sections 3.3.15 and 3.3.1! 
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3.3.11 1 or .10 - The Index Of Function 

Format 

dyadic 

Argument Types 

The left argument must be a vector. The right argument can be 
any scalar or array. 

Definition 

Returns the index in the left argument of the first occurrence of 
the value in the right argument. The result of a dyadic iota 
operation always has the same shape as the right argument. That 
is, the result returns an index for each of the values in the 
right argument. 

If the value is not located in the vector specified as the left 
argument, APL reports a value equal to the number of values in 
the vector plus 1, ((pi4) + l). 

The right argument need not be a single-element array; it may 
have many elements and many dimensions. The right argument can 
also contain literal characters. 

The result of a dyadic iota expression, for example X^BxA, always 
has the same shape as the right argument, formally pZ is the same 
as pA. If i4 is a matrix, the correspondence between A and X can 
be expressed as XLI;J1 is the smallest K such that ALI;J1 is 
equal to 5CZ3. 



Examples 














B 




4 


9 


6 


B 




6 






EM A 




3 










1 






K-i:: '■'::! 




9 






»i::bu-/k<;:i 




9 






EM-o :i. 2 3 

Af-3 2f6 5 

B 


4 5 6 7 8 9 
3 2 9 





1 


2 


3 A 5 6 7 


8 9 
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A 


6 


'5 


3 


2 





9 


7 


6 


4 


3 


1 


:10 




■ AX^CDKiFGH ' \ ' hii:;:fti:'i:i:i:' • 


8 '5 


14 5 4 




Bi-^ 4 2 3 7 8 




A<-2 2fl4 




BX A 


7 


3 


A 


2 



f) ' A ' ==2 ^^ L.f::GAl.. , SO 115 \ WITH CHAHt A>ai hiUMERIC AP:OS 



Related Functions 

Index Generator, Section 3.3.10 
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3.3.12 , - The Laminate Function 

Format 

dyadic 

Argument Types 

Both arguments can be scalars, vectors, or arrays. 

Definition 

Joins scalars, vectors, or arrays along a new dimension. The 
syntax is the same as the catenate function. Section 3.3.1. 
However, the coordinate specification ([]) is usually a fraction 
to indicate a position between existing coordinates in which the 
new coordinate is to be placed. (The coordinate is dependent 
upon the index origin. Section 4.2.11.) 

If two arguments in a laminate operation do not have the same 
dimensions, then at least one of them must be a scalar value. 



Examples 



i:ik-:f 
2 3 



ie<E 



0<->:<!-' ABC y i;:o,5::i '^^^' 



(^ >■• 



n CREATES A HiiKw D :i: M lii: H s :i: o N bk-ifor 
ft T H i-i: ("■ :i: i=i: s r o h b p (^ t< x:> s e^ r o w 

i::i<..xf. ' ABC ,i:::i. ,3:1 • bef' 



f K 



H CREATES A NEW D IK MEHS :i: OH AFTEI- 

n r' I-I Hi: i"' ;i: r s t o h lii: 5 f>i x.' x:i s f-^ c o i.. if m h 
[■| (■■ x:< <•■ 3 2 f ' ^••' '^■' w '< f z ' 



uv 
wx 



f^^-3 2r ' a.bcx:iK::f • 

l-':<"Ay 1:: «2:]B 
fR 

2 3 '■'* 

f'-i-f^'v 11 *9;.|B 

f R 

3 2 2 

"=:<•■ A J, t;;2*3:;|B 

/> R 

3 ':> ';> 

>=':<-«yi:.5:;i '^' 
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"^3 2 



C1C« 



K-.F 

/.R 

3 2 2 

' r- ' y i:; 2 » 5 ;] « 

r •» 
v c 

YD 

YE 
Y !•" 



Related Functions 

Catenate Function, Section 3.3.1 
Ravel Function, Section 3.3.14 
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3.3.13 £ or .EP - The Membership Function 

Format 

dyadic 

Argument Types 

Both arguments can be arrays of any dimension; the left argument 
contains the elements by which membership in the right argument 
is determined. The arrays need not have the same rank. 

Definition 

Determines whether or not particular elements of one array occur 
as elements of another array. The result is a Boolean array 
whose shape is the same as that of the left argument. 

The result consists of only Os and Is; a 1 indicates that the 
corresponding element in the left array is present in the right 
array, indicates that it is not present. 

Examples 

.1. 1 :l. 

A/ ' ttBCX:'l:::i"G ' 
At'li:: 



The compression function /, is helpful here in identifying the 
particular characters that are members of the vector. 

A<!-2 3r-7 B 2 4 6 9 

A {• 1 6 
1. 
;L 1 

3 4?; '34' 








3 4 j; \ 



f) ' A ' :=:2 I?> LEGAL., SO XS £ WITH CHAR AND HUMERXC ARGS 
' AAA ' g 2 







Related Functions 

Index of, Section 3.3.11 
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3«3.14 , - The Ravel Function 

Format 

monadic 

Argument Types 

The argument can be any scalar or array. 

Definition 

Produces a vector from any scalar or array. The vector produced 
has the same length as the original array. The elements of the 
array are preserved in the resulting vector in row order. If the 
argument is a scalar, then the ravel function produces a vector 
containing one element. 



Examples 












f-^ 








1 


2 3 








4 


5 6 






2 


3 


LH-Bf 


„A 




1 


2 3 


4 5 


6 




6 














Qi-fU- 


■2 3 


4f 190 




1 


2 


3 


4 




I'j 


6 


7 







9 


10 


11 


12 




13 


14 


IS 


16 




17 


18 


19 


20 




21 


22 

uA 


23 


24 



1 2 3 4 5 6 7 e 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 
24 

2 3 4 



Note the difference in the shape of a scalar and the shape of a 
scalar to which the ravel function has been applied 



f4 

f y4 
1 

Related Functions 

Catenate, Section 3.3.1 
Laminate, Section 3.3.12 



(APL outputs a blank line) 
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3.3.15 p or .RO - The Reshape Function 

Format 

dyadic 

Argument Types 

The left argument can be a scalar or a vector. The right argu- 
ment can be a numeric constant, or a literal character, or the 
name of an existing array. A literal array can be constructed 
by including a character string as the right argument and enclos- 
ing the string within single quotation marks. 

Definition 

Constructs an array or reshapes an existing one. The left argu- 
ment specifies the shape of the array; the right argument speci- 
fies the values to be assigned to each element of the array. The 
shape of the array describes both the number of dimensions of the 
array and the number of elements in each dimension. The values 
are placed in the array in row order; that is, the first value is 
placed in row 1 column 1; the second value is placed in row 1 
column 2; the third value is placed in row 1 column 3, and so on. 

If the left argument is a single value, a 1-dimensional array is 
created. 

The array being reshaped need not have the same number of values 
as the array from which the values are taken. If the right 
argument has too many values, the excess values are ignored from 
the right. If there are too few arguments, the values are du- 
plicated from the right. 

Any number of array elements can be specified in a reshape 
operation as long as the number is not negative or fractional and 
does not generate a vector or array too large for your workspace. 

Examples 



3^1: 



:■• '"! 



vJ xJ vJ 



9f ' ABC ' 

A»CABCABC 

Xi-S 9 7 4 

Iff" 2 2f'-' 
'■(' 

B 9 
7 4 

<>i-l 2 3 4 
2 5fA 

1 2 3 4 .1. 

2 3 4 :l. 2 



3r« 



1. 2 3 
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1 2 
3 A 



The following expressions each generate a null vector: 



(APL outputs a blank line) 

(APL outputs a blank line) 

(APL outputs a blank line) 

(APL outputs a blank line) 





f, SHAPE WITH A <HCAI..AHi 




A<!-:1 




/>A 




Of ' ' 




OfO 




\0 




a<«<-3 5 4 f« 




f A 





S A 



Related Functions 

Shape, Section 3.3.1! 
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3.3.16 <t) or .RV and e or .CR - The Reverse Function 

Format 

monadic 

Argument Types 

The argument can be a vector or array. 

Definition 

Reverses a vector or the elements of one coordinate (last 
dimension) of an array. It changes the order of the elements, 
not their dimension. 

To specify the coordinate to be reversed, include it in square 
brackets. (The coordinate is dependent upon the index origin. 
Section 4.2.11.) The default is the highest coordinate (last 
dimension) of the array. The special character e (.CR) reverses 
the first coordinate of the array. 

The reverse is formed by overstriking the circle o with the 
residue function | . The © character is formed by overstriking 
the circle (o) with the minus (-). 

Examples 

12 3 4 
5 6 7 B 

5 6 7 8 
1 2 3 A 

(D[:2:]A 

4 3 2 :l. 
8 7 6 5 

©A 

5 6 7 8 
12 3 4 



The following example reverses a matrix in both dimensions 
simultaneously : 

<■•'•<<•■ 2 3f\6 
1 2 3 
4 5 6 

(i»(t)i::i::i'' 

6 5 4 
3 2 1 
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Reverse is not the same as transpose: 

1 4 
3 6 

Related Functions 

Rotate, Section 3.3.17 
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3.3.17 (|) or .RV - The Rotate Function 

Format 

dyadic 

Argument Types 

The left argument can be a scalar or a vector. The right argu- 
ment can be any array. 

If a vector is being rotated, the left argument must be a scalar 
or a 1-element vector. If a multidimensional array is being 
rotated, the left argument must be a scalar, a single-element 
vector, or a vector whose elements correspond to dimensions of 
the array being rotated, with the dimension being rotated omitted 
from the vector. 

The rotate function is formed by overstriking the circle o with 
the residue function | . 

Definition 

Rotates an array by a specified number of places. A positive 
rotation causes a left shift; a negative rotation causes a right 
shift. 

You rotate a multidimensional array by specifying the coordinate 
along which rotation is to take place. (The coordinate is de- 
pendent upon the index origin. Section 4.2.11.) The default is 
the highest coordinate of the array. 

To specify the first coordinate, use the special symbol e (.CR) 
which is formed by overstriking the circle o with a minus -. 

Examples 

3<D\S 
4 5 :l. 2 3 

•••■3<D\5 
Z A 5 1 2 

H ^■■ 3 4 f ' f^ B c X' e: f g h x ,. • k i... * 

EPGH 

1 J l< 1... 



ABCX!" 
FCvHh": 

i< I.. :i: ,j 

EFKD 
.T JCH 
ABGI... 

ABODE 

i="gh:i: J 

KLMNC) 



1 2(|)>< 



112 3<t)i::i:i>! 



P <.. A f. 3 5 f> I A B c x:» k: F (5 H t ...i i< l. m n o • 
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;1. "l 2 2 2»'^ 

FLMNO 
KBC!t:>E 
AGHXvJ 

5 2 " 1.(D« 
ABCDE 
HXUFG 

OKI...MH 



Related Functions 

Reverse, Section 3.3.16 
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3.3.18 p or .RO - The Shape Function 

Format 

monadic 

Argument Types 

The argument can be scalar, vector, or array. 

Definition 

Returns the shape of the argument, that is, it returns the length 
of a vector or the dimensions of an array. For example, if the 
argument 5 is a character vector consisting of ^ ABCDEF" , then the 
following expression returns the number of characters in the 
array: 

Bi- ' ABCXJEF ' 
ABCDK::F 

6 



If the argument is a matrix, rho returns the number of rows and 
columns it has. For example: 

A <••;:; 6/mIO 

fA 



If the argument is a scalar and not a vector or array, then the 
rho of that scalar is a null vector, a vector of length zero. 
APL outputs a blank line in response to the shape operation with 
a scalar. Two shape functions (pp) return the number of dimen- 
sions (rank) of the arguments as follows: 

Argument ppZ 

scalar 

1-dimensional array 1 

2-dimensional array 2 

3-dimensional array 3 

and so on. 

This effect is the result of the fact that pK is a vector con- 
taining one element for each dimension ofK, so its p ippK) is 
a 1-element vector consisting of the number of dimensions of K. 
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5 6 



1 


2 


3 


4 


5 


6 


7 


8 


9 


:i.o 


1 


'? 


3 


4 


5 


6 


7 


8 


9 


1.0 


:l. 


'? 


3 


4 


5 


6 

f A 

ff A 

Kf.3 
f K 


7 


B 


9 


:l.O 



(APL outputs a blank line) 



Related Functions 

Reshape, Section 3.3.15 
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3.3.19 f or ^ - The Take Function 

Format 

dyadic 

Argument Types 

The left argument can be a scalar. However, if the right argu- 
ment is a multidimensional array, the left argument must be a 
vector containing one element for each dimension of the array. 
The right argument can be any array. 

Definition 

Builds a new vector or array by taking a specified number of 
elements from an existing array. If the value of the scalar is 
greater than the number of elements in the vector, the resulting 
vector is extended so that its length is the value of the scalar. 
Zeros extend numeric vectors, and spaces extend character vectors 

In the expression R-^S^-V, if S is positive, then R consists of 
the first S elements of V. If S is negative, then R contains the 
last \S elements of 7. If [£" is greater than the number of 
elements in 7, then zeros or blanks are inserted in R before the 
values of V. 



Examples 



1 2 



2t\3 



4 1^3 

12 3 

:l 5f ' API...SF ' J Bt5 

«pi._SH-- 5 

■■■•6t:l.2 24 3S 48 

1.2 24 3S 4S 
■■•■5t\3 

:l. 2 3 

5tl3 

1 2 3 

■■•■20 t ' TEST ' 

T B. s r 



Related Functions 

Drop, Section 3.3.5 
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3.3.20 ^ or .TR - The Monadic Transpose Function 

Format 

monadic 

Argument Types 

The argument can be a matrix or higher-dimensional array. 

Definition 

Transposes the dimensions of an array. For a matrix, it exchanges 
rows and columns. If you use a vector as the argument, it will 
have no effect. For example: 

Afj. 2 3 4 S 
12 3 4 5 

To form the ^ symbol, overstrike the circle o with the slash \. 

Examples 

t:H-Af.2 3fl6 
:l. 2 3 

4 S 6 

:l. 4 

2 5 

3 6 

f ftjA 

3 2 

P^B<!-2 3 4/M8 
12 3 4 

5 6 7 
12 3 4 

5 6 7 
12 3 4 
5 6 7 
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fi)B 


:l 


5 


s 


.1. 


1 


5 



3 


7 


7 


3 


3 


7 


4 


8 


8 


4 


4 


8 




fhjB 


4 3 


2 



Related Functions 

Dyadic Transpose, Section 3.3.21 
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3 .3.21 ^ or .TR - The Dyadic Transpose Function 

Format 

dyadic 

Argument Types 

The left argument must be a vector containing one element for 
each of the dimensions of the array to be transposed. The right 
argument can be an array. The shape of the vector expresses the 
rank of the right argument. For example, in the expression V>S)A , 
the rank of the right argument can be expressed as: pV which 
must be equal to ppA. Thus, V must have two elements if .4 is a 
matrix, three if ^4 is a 3-dimensional array, and so on. 

If the rank of the array is 3, then valid values for the left- 
argument vector can be 111, 121, 132, 312, but not 13 1 
(2 is missing) . 

Definition 

Permutes the coordinates of an array. The following table lists 
transpositions for a variety of arrays; 

Table 3-6 
Transpose Definitions 



Expression 


Shape of 


R 


Definition 


R^1>S)V 


pV 






R^V 


R^l 2^ M 


pM 






p<-M 


R<-2 l^M 


(pM)[2 


1] 




RLI;J']<-M\:J;I1 


R<-1 l^M 


l/pM 






RLi:\^MLl;Il 


R<-1 2 3M 


pA 






R^A 


R^l 3 2>SiA 


{pA)ll 


3 2] 




RLI;J',K1<-ALI;K;J:\ 


R^2 3 l>SiA 


(p^)[3 


1 2] 




RLI;J;K1^ALJ;K;I'] 


R<-3 1 2>SiA 


{pA)l2 


3 1] 




RLI;J;K2^ALK;I;J:\ 


R^l 1 2tS)A 


(L/(p^)[l 2]) 


,(p4)[3] 


RLI;J1<-AZI;I;J1 


R^l 2 1>S)A 


(L/(p^)[l 3]) 


,(p^)[2] 


RLI;J1^ALI;J;I1 


R^2 1 IM 


(L/(p^)[2 3]) 


,(p^)[l] 


RLl;j:i^ALJ;I',i:\ 


R^l 1 1^^ 


l/pA 






RLll^ALl;I;i:\ 
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Examples 



[;h-A<-2 3r\6 

2 3 
5 6 
flX:iYftr<:i:c sometilmes same as monaxiixc 

tSjA 

4 



2 :l.h?« 



3 4 



6 

4 

6 
fM-2 3.fM6 

A 

2 3 
5 6 



«<!-2 3 4/M6 

A 

3 4 
:l. 2 
5 6 



2 3 4 

6 ;l 2 

4 5 6 

2 1 :!.<«« 



:l. :l. 



Related Functions 

Monadic Transpose, Section 3.3.20 
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3.4 EXTENDED FUNCTIONS 

APLSF provides extended functions to perform a variety of matrix 
operations and to aid in data formatting. These functions are: 

1. The Matrix Inverse and Matrix Divide functions @, Sections 
3.4.1 and 3.4.2 

2. The Execute or Unquote functions e and ±, Section 3.4.3 

3. The Extended Execute function t, Section 3.4.4 

4. The Dollar Format function $, Section 3.4.5 

5. The Monadic and Dyadic Format functions t. Sections 3.4.6 
and 3.4.7 

6. The Quote function t. Section 3.4,8 



3.4.1 B or «DQ - Tho Matrix Inverse Function (Quad-Divide) 

Format 

monadic 

Argument Types 

The argument can be a scalar, a vector, or a matrix. 

Definition 

Inverts a matrix to facilitate matrix division and a variety of 
other matrix operations. 

The domino symbol is formed by overstriking the quad character 
(D) with the division character (*). 

Examples 

0*5 0.3333333333 O.ilV^i 

0*3333333333 0.25 0*?. 

[:HMM3A 

9 " :'>6 30 

■■Z6 192 ■■'■:l.00 

30 "Mno :liJO 

9 -IB 1.0 

10 "A5 3 A 
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Related Functions 

Matrix Divide Section 3.4.2. The monadic expression iZ is equal 
to the dyadic I^X , where J is an identity matrix whose order can 
be described as IfpZ. If the argument of the matrix inverse is 
a scalar, the expression iZ is equal to ^X. 
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3.4.2 i or .DQ - The Matrix Divide Function (Quad-Divide) 

Format 

dyadic 

Argument Types 

Both arguments can be scalars, vectors, or matrices. 

Definition 

Performs more complicated matrix operations than the inversions 
described in Section 3.4.1. In the expression XBI , X and 7 must 
conform to the following: 

1. Y must have a rank of 2 or less. 

2. If the dimensions of Y are M hy N , then M>N . 

3. X must have a rank of 2 or less and (l-\-pY) = li-pX 

This implies that matrices X and Y have the same number of rows, 
and the columns of Y are linearly independent. If Z^XEY , then 
ppZ is the same as ppZ and +\ ( ( 7+ . xz ) - j)*2 is minimized (least 
squares solution) . 

The matrix divide treats scalar arguments as matrices containing 
one row and one column. The expression Z@J is equal to scalar 
division X^Y, except that the operation OfflO produces an error 
condition. If the arguments are vectors, they are treated as 
matrices with a single column. If I is an identity matrix of the 
same dimension as X, then iZ is equal to J@Z. 



Examples 



The following example illustrates the use of the matrix division 
function in solving these linear equations: 

3A+B=9 
2A-B=1 

In the expression X^Y , Y is a matrix whose values are the coef- 
ficients of the equations, and J is a vector containing the 
values 9 and 1. 

>'^9 :l. 

■>i-2 2f3 1 2 ""1 



The result is a vector in which the first element is the value of 
A in the linear equations, and the second is the value of B. 
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The following examples illustrate the use of the matrix divide, 
including a least squares solution; 

0<"'==><-(2 If 2 5)y:L 
2 1 
5 1 

E<MO 19 

Af » XX 

10 19 

n<-«<-(5 1/M5)yl 

1 1 

2 1 

3 1 

4 1 

5 1 

»<-2»001 2*998 4*002 4*997 6*01 

1.0017 0*996S 
BfA-j. , x>; 

OfX'<!-0A 

"•2*000000000k:""1 "1 * OOOOOOOOOH""! 2 * 923B7SB22K"""20 
1 * 0000000001-=="" 1 2.000000000k:""1 
8 . OOOOOOOOOEi: "1 5 * 000000000'=: "1 2 * OOOOOOOOOk:: "1 
"1 *000000000^^"1 "^.OOOOOOOOOK":!. 
x+* xA 
1 * 000000000^:0 5 *421010e62Ki:""20 
"1 * 301042607<==""18 1 * 000000000n.=:0 



Related Functions 

Matrix Inverse, Section 3.4.1 
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3.4.3 £ or 1 .EP or .DE - The Execute Function or Unquote Function 

Format 

monadic 

Argument Types 

The argument can be a scalar or a vector. If the scalar is 
numeric, the value of ek is egual t.o A. If the scalar or vector 
is a literal, APL evaluates it exactly as quad input from the 
terminal would be evaluated. 

Definition 

Executes a character string as an APL statement. The scalar or 
vector included as the right argument of the function is evalu- 
ated as the character string to be executed by APL. The e and 
1 can be used interchangeably to indicate the execute function. 

APL treats carriage return/line feeds in the argument as state- 
ment separators, just as they would be if they were input from 
the terminal, so multiple lines are allowed. The result of the 
expression R-^&A is the value of the last statement evaluated in 
A. If the last statement has no value, i? is a null vector. 

Errors encountered in the character string processed by the 
execute function are handled exactly as if they occurred in 
statements entered from the terminal. If an error is encountered 
while evaluating the execute string, an error message is output, 
and the segment of the execute string currently being evaluated 
is displayed. No further evaluation of the string is performed. 
The €A returns a null array whose shape is S", where £" is a 
number indicating the error that was encountered. Appendix A 
contains a complete description of all APL error conditions. 

The execute function is also known as the unquote function, 
because it strips quotes from the value entered as its argument. 
Other uses of this function include: 

1. Function definition (character-editing commands are not 
permitted) 

2. Conversion of vectors of characters representing numeric 
constants into numeric values 

3. Passing an unevaluated APL name to a function. (The argument 
can be evaluated with e -inside the function.) 
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Examples 



The following examples illustrate the use of e in function 
definition, system command execution, and APL statement evalu- 
ation: 



Z i- Z X Z. 



B<-4 

flp XB HOT DHFJtHEi:' 

I"' 

j. i VAI._lii;:: ERROR 
!"• 
A 

C<-{: A 

/.- (;: 


f^F xs WOW )C'I:::f:i:ni:::x:> 

49 

F 

3t-2 

6* 

9 



e:; 

1;|. VAUUKi: ERROR 

Hi: 

A 

3*-2i. 

4' 

10 

7 f: SYJ-riAK ERROR 
3*-2y 



7 



a • ) ERASE ' „ j: ' ) VARS ' 

flALi... var;i:abi...es are now erased 

i:i; 
:l. i VALUE error 

Iff: 

A 

)ws:i:x:> th:i:sws 

WAS ei...EAI=i: WS 
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II 1 "I ' 'f' '"' ^ - ^ ■■• HARD T O B E L 1 E V K: ' 

II 2.'] Z<. (:')SAVE THXSWS' 

II 3 II ' ''"' '"' ■=•• ' •' '- ^-^ ^-^ ^' ■=• '^' y •=• ■•■' •=■ '^- 1-^ T" 1 O N F: E." S U M E S AFT E P: E X E C U T E 

AUTOMAT ;i:C A L_L r ' 

II 4 II "^ 

H 

this :is hard to beilxeve 

when loaded y exe cut .ton resumes after execute 

automat:i:cai...i_.y 

)l..OAD TH.TSWS 

w i -i e m i... o a x:i e d j. e x e c u t :i: o m r b s u m e s a f t i:-; i-: i;-: x e c u 7' b 
automat:i:cai...l..y 

flTHE NEXT EXPRESSION DbK=;S NOT FR:i:NT A VAL.UE 
nTHE NEKXr ONE DOES 

5 

Df.^: ■ • 
/>D 



The last example illustrates that the execute function always 
returns a value. Because, in this case, there is no value ex- 
pressed in the character string, the value of the operation is 
simply a null vector. Similarly, if the character string con- 
tains a branch (^) , the execute function does not transfer 
control but returns the null vector. 

Note that you can use )ECHO ( OFF), Section 5.5.2, to suppress 
the error message from e . 



Related Functions 

Extended Execute, Section 3.4.4 
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3.4.4 A or .XQ - The Extended Execute Function 

Format 

monadic 

Argument Types 

The argument can be a scalar or a vector. 

Definition 

Processes system commands and supports the entry of multiple 
lines. The execute symbol i is formed by overstriking the 
decode or unquote character i with the jot character °. 

The i function is very similar to the e or i functions. However, 
there are two major differences. If an error is encountered in 
the character string being executed, i does not return a null 
vector indicating the type of error. Instead, i generates an 
error message for the line on which the actual execute occurred. 

The second major difference is that if the i character string 
contains a branch (->) , control passes to the specified function 
line. 

Examples 

t:i::i ^•'<-.«.'^'» 

i::2::i ^ 

F . 3 , . 

7 .f. SYNTAX ERROR 

A 
25 l:i:KECt.rn::: EPirROR 

'^n::i. ::i »<■■,* a 

A 

)s:r 

f.< 

11 VALUE ERROR 
B 

A 

f" ' ' 

Xl VALUE ERROR 

'=^'t::i. ::i »<•■.! a 

A 
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In the last example, a value is required in the execute string, 
but none is included. APL generates an error message and 
suspends function execution. 



Related Functions 

Execute or Unquote, Section 3.4.3 
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3.4.5 



- The Dollar Format Function 



Format 

dyadic 

Argument Types 



The right argument can be one or more scalars, vectors, or 
multidimensional arrays containing numeric or character fields 
to be formatted. The left argument is a character vector con- 
taining one or more format fields describing the type of format- 
ting to be performed on the specified fields. The left argument 
is enclosed in single quotation marks. 

Table 3-7 summarizes the syntax of the format fields. 



Table 3-7 
Format Fields 



Format 


Meaning 


'MAW* 


Character data - cannot be used for numeric values 


'MEA/.d' 


Floating-point numeric data with exponent 


'MQFW.d' 


Fixed-point numeric data 


'MQIW 


Integer numeric data with automatic rounding 


'MXW 


Blanks inserted in edited line 


•y^QtextH' 


Literal text inserted in edited line 


where 




M 


is an optional repetition factor (number of 
values to which the format is to be applied) . 


W 


is the width of the field. 


d 


is the number of decimal positions. 


Q 


is any number of qualifiers (see Table 3-8) . 



The lamp character (o) , formed by over striking the down union 
(n) with the jot (°), can be used instead of the quote-quad (n) 
On non-APL-keyboard terminals, .QQ replaces [3 and " replaces (\ . 
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Table 3-8 
Qualifiers 



Qualifier 


Meaning 


B 


Blank field if value is 


C 


Insert commas 


L 


Left justify 


Z 


Fill with zeros 


Mdtexta 


Insert text left of 




negative result 


NQtextCl 


Insert text right of 




negative result 


PHtextCl 


Insert text left of 




nonnegative result 


QEtextCl 


Insert text right of 




nonnegative result 


RHtextB 


Insert text in background 



If more than one format field is included in the left argument, 
the fields must be separated by commas. Successive fields apply 
to successive vectors or arrays represented by the right argument 
of the function. If you include a repetition factor in one of 
the format fields, this factor indicates the number of vectors to 
which that format is to be applied. 



Definition 



The result of a format operation is one or more lines of edited 
text. Each resulting line consists of one edited row of each 
array in the right argument, where each vector (F) is treated as 
an array of dimensions (p7) by 1. The total number of lines 
produced by a format is equal to the longest column in the array 
contained in the right argument. The columns of values with 
shorter columns are extended with blanks. 

As many as 18 significant digits can be specified in a format 
statement. A format field that requests more than 18 significant 
digits will cause digit positions to the right of the decimal 
point to be filled with blanks, and digit positions to the left 
of the decimal point to be filled with underscores. A minus sign 
is output on non-APL-keyboard terminals. 

A format field that does not specify sufficient room for all 
significant digits plus any inserted characters causes the entire 
field to be filled with stars on APL terminals and asterisks on 
TTYs. 

If a format expression produces a very large matrix that is not 
assigned explicitly to a variable name, APL saves storage in the 
workspace by displaying each line of the matrix as it is format- 
ted and not saving the results. 

As in other languages that support format specification similar 
to this APL function, parentheses can be used to repeat groups of 
fields. They can be nested to three levels. 
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Examples 






'3:4'$( \5P10M6) 


1 


3.1 


2 


12 


3 


13 


4 


14 


5 


15 




16 




'ZFA.i '$1 2 3 


01 fO 




02*0 




03 ♦O 





Af'F4»2y3(3'2yE:e»l) yAl ' 
fllS EQUAL- TO 

^i- ' F" 4 » 2 y :i: 2 y ^S ♦ 1 y :•: 2 y ^B . 1 y :<: 2 y f^3 » 1 y « 1 ' 
' 1'5'$3 "7 4*7 4*2 
3 
""7 

4 

'3:5'$(3r"7y4*7y4*2) 

3 ""7 5 4 

OfA<.. ' l=-6 » 2 ' * ( 3 y 6 y "7 J 4 ♦ 3 ) 

3^00 A* 00 ■■■■7»00 4*30 

0<..Af. ' FA. 2 ' $ ( 3 y 6 ""7 y 4 . 3 ) 

3«00 6»00 4»30 
••■■7»00 

fA 

2 18 

«)f-2^-25 

'l=="30»2'$5:i 

200000000000000000. _..-♦ 

'i=-"3,2'*50O 

A<-2 3f <6?9999) MOO 

' :<-"4 y CI m y "6 t 2 y '<Z y K^IO ♦ 2 ' $« 
351 51*19 8»9k:0 

701 29*36 9»0Ki:i 

' AJ. ' $ ' AK" 
B 



' A3 ' <1> ' AE<C ' 



T <•• 4 7 f ' F- E n s F- E f< cr :i: i... s f- (^ f- E F: r o r a i... < 

cosTf. ,19 »05 .01 

AMHTf.20 50 2509 
T c o s r i~ A Mi-nx c o s r 

' 7 A 1 y a I a , 1 6 y ^■=•8 ♦ 2 y ••■'■ 1 2 . 2 ' * < T ? amnt j cost j tcds t , .f/reosr ) 
PKHS I 20 0*19 3*80 

PENCILS I 50 0t05 2.50 

fafef:: | 2589 0.01 25.89 

TOTAL I 32.19 
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'«-~23A'56*7S ""25 "O^A »8 100 



■■•■23456 » 8 
•25*0 
■■■■0»4 

0»8 
100*0 

'CBIIO' $'•< 
'"2ZyA'57 
■■■■2!3 

1 

100 

■023456 ♦a 
-000025 ♦O 

■"000000*4 
0000000*8 
0000000*0 
0000100*0 

'L.t9'f>-' 

7 SYNTAX ERROP: 
•I...19'$X 







' 1... : 


1:9 '$X 




■■■■234 


57 








■■■■25 











1 











100 














'MB i!|r 


11*2'$* 


• ^:> 


34; 


56, 

25. 

•0 

0< 

0. 


► "78 
*00 

► 40 

► 80 

► 00 






100. 


► 00 
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'P:|!l + l!|pa-*l!|:i:il ' $>' 
■*■+■*■■*■■*■ ""2'3 A '57 
+++•»■+■♦•+•♦•■" 2 5 

•♦•■♦••<-f-f*-*-f»-fl 
•f ■■♦••*■ 1+ •+•+ + •♦■•♦■ 

■t •4-J-f-t-f-ff .1.00 

•Mi::r"^inFi!i$i!i»>'=:i..i,2'*: 

"■■*23456.7e 
"•■$25»00 



■•••*0,40 

$o*eo 




Hi 100*00 




' '^a i!i<" 


':t20'$'-i 




■■"23 y 457 

.... ,.j |... 




* 

•1 




.1. 


:i,oo 



'i=':|!UnFrai|>aci==-:l.l.2' $P' 
A$23y456*78 
Heft Art ft $25* 00 
ft ft ft ft ft ft $ ♦ 4 
ftftftftftft$Ot 80 
A ft ft ft ft rt$0*00 

*ftftft$;i.oo»oo 

' '••■• I'l '•< f :> f' ':=: CI JK< I"" 9 , 2 ' ^■> '' 

■"23456 ♦ 78 

"25,00 

■"0*40 

0*80 

100*00 

'MpKO ii\i\)n «l!l l!l 1^=10*2 '$■••: 

(23456*78) 
(25*00) 
(0*40) 
0*80 
* 00 
100*00 

23456*78 »» 

25*00 IC'B 

0*40 3t:.x:. 

0*80 <:■!=■: 

100*00 ("i^^: 



Related Functions 
None 
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3.4.6 T or .FM - The Monadic Format Function 

Format 

monadic 

Argument Types 

The argument can be a scalar or an array of any shape and either 
numeric or character data. 



Definition 



Converts numeric arrays to character arrays. When applied to a 
character scalar or array, the result of the format R^-^A is an 
array identical t.o A. If ^4 is numeric, then the character array 
represented by R will be identical to A as it appears when dis- 
played by APL. However, the blank characters displayed along 
with the values of A will actually be a part of the new array R. 
The format of a scalar number is always a vector. 



Examples 



The following example illustrates the difference between the 
shapes of a displayed numeric array and a formatted character 
array : 





«<-2 4f\B 




V.<i.y(\ 




A 


1 


2 3 4 


5 


6 7 8 




pA 


2 4 






B 


1 


2 3 4 


b 


6 7 8 




f>B 


2 1 2 






i;* [: J 3 X \ 4 :i 


1234 




15678 





Related Functions 

Dyadic Format, Section 3.4.7 

System variables DPP Section 4.2.15 
UFW Section 4.2.16 
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3.4.7 T or .FM - The Dyadic Format Function 

Format 

dyadic 

Argument Types 

The right argument must be a numeric array. The left argument 
can be a scalar, a pair of numbers, or a vector whose length is 
no more than twice the number of columns in the numerical array. 
The left argument controls the format of the result. Two numbers 
are usually supplied as the left argument. The first number 
specifies the width of the numeric field, and the second sets the 
precision of that field. 

Definition 

Provides output control exceeding that available with the monadic 
format. It offers a number of formatting options but does not 
provide the comprehensive formatting capability available with 
the dollar format function {$) . 

Dyadic format provides a powerful tool for formatting tables, 
headings, and labels. Precision is expressed differently for 
decimal values and in scaled exponential forms of output. The 
form is determined by the sign of the precision argument. For 
decimal output, precision is a positive number, expressed as the 
number of digits to the right of the decimal point. For scaled 
output, precision is negative and is the number of digits in the 
multiplier. 

If the width of the specification is zero or omitted from the 
expression, APL provides a default width such that at least one 
space is inserted between pairs of numbers. If only one number 
is provided as the left argument, the number is assumed to re- 
present the precision of the result, not its width. 

In general , the width must be large enough to accommodate the 
number field. However, APL does not require that space be in- 
serted between columns. 

You can specify width and precision arguments for each column of 
the array to be formatted or even for each element of the array. 

A format operation can also be specified for a multidimensional 
array and applied to the last two coordinates. 
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Examples 



31*16 





■■■•J.5»S78 


B 


2 3 

D <•••'■ 4- 12 3^'i 




31. ♦lAO 


0»000 


■":L5*S7B 


B » 000 


2 36 

«<-9 ^2v'< 




A 





■•.I. ♦o? 

■235*61 



•■:l. t070 
■235.610 



31.16 0.00 -l.O? 

-15.58 B.OO ■■235.61 

a<-'=^:4-6 0^>' 

31 -l 

-16 ■■■■236 

2 IB 

3.115^1 -l.l'J^^O 

"1.61^1 B.0Ki:0 ■■2.4'^^:2 

at.-Ci-7 -1-V5? 
3k:i ""IK^O 

•-2k;;i 8";;:o ■■2K^2 

fl C O I... U M H F O ¥■: M A T' I' X H Ci 

fi::i<-B ■2 8 ^'< 

31 -1 

-16 8.0Ih:0 •236 

2 25 

1"- o P: M f>i T r 1 N G f-^ M u I... T' :i: x:' :i: m i;;: h s ;i; o h (^ i... f>i p: i-;.- (■>> r 

f;\tf>ii-2 2 2.1" \ 8 
1 2 
3 4 

5 6 
7 {;} 

5 2y« 

1.00 2.00 
3.00 4.00 

5.00 6.00 
7.00 8.00 

B 

3.1H1 ■ 1.1 HO 

"■■1.61;;: 1 B.Oi^^O ■2.4i;;:2 



i:m-3 3rl 1 1 1 1 1 
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r A B I... E F" C) R M A T T X ii G 



I-: O W S i- '5 7 f- ' /:^ I"- L. f" O R T R A ii C C) » O U X;< C^t S I C P L. 1 

COLSf' USERS PROGS SYSTS • 

^ORM^5 3f A 

< ' ' y t: 1. ::i f^- » w s > , c o i.„ s ^ i: j. :j 7 ■»■ •=• o r m 

usi;;;rs progs systs 

«f-i- :l. 2 3 

I"- OR T RAN 4 S 6 

CO 1^0 1... 7 

BAs:i:c 2 



Related Functions 

Monadic Format, Section 3.4.6 



e 


:l. 


3 


4 


6 


7 
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3.4.8 T or .EN - The Quote Function 

Format 

monadic 

Argument Types 

The argument can be a scalar or an array with either numeric or 
character data. If numeric, APL converts it to a character 
string. 

Definition 

Converts numeric values to character strings and also provides 
aid in preparing text to be processed by the execute function. 

If the argument is already a character string, APL determines 
whether or not the string represents an identifier (for example, 
a variable name or function name) . If the character string is 
not an identifier, then APL returns a null vector. If the 
argument if a variable, APL returns the value of the variable. 
If the argument is a function, APL returns the lines of the 
function definition, separated by pairs of carriage return/line 
feed characters. 

Examples 

In the following example, array .4 is converted to a 20-character 
vector (spaces output by APL are included in the size) in which 
the character representations of 1 through 6 are members, but 
the corresponding numeric values are not. 

E< 

1 2 3 
4 5 6 

f B 

20 

' 1.23456' €» 

1. :l :l. 1 1 1 

( I 6 ) c B 
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■^ -''a '■7$^':^.jVr^ ^:;-?^St?i3?;'^ '-t^^-f^ii;^?<:- 
In the" following 'estaitt-^le, the tikier'^iSi^'f ined f urictiibii "(^ is effec- 
tively restored by the use of the character string that repre- 
sented this user-defined function in an execute operation. 





VJIfA <S E' 


i::i::i 


2:f (3xA)-».4x£' 


i:2::i 


2 <••:?:; A 2 


£:3:i 


V 




2 <^ 1. 


:100 






[;j<.oj.., 'f^' 


V '^- <•■ fi 


Cv B 


'-^^taxA) f4xE' 


Zi"Zf(', 


;> 


V 






)i:-:: raise: g 




2 « .1 


7 s 


TNT AX ERROR 




2 <;' 1 




A 




i-c.^ 




2 t:i 1. 



100 

Related Functions 

Unquote, Section 3.4.3 
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3 . 5 OPERATORS 

An operator differs from a function in that an operator takes a 
function as its argument. The following operators are available in 

APL: 

1. Inner Product Section 3.5.1 

2. Outer Product Section 3.5.2 

3 . Reduction Section 3.5.3 

4. Scan Section 3.5.4 

3.5.1 f . g - The Inner Product Operator 



Format 

dyadic 

Argument Types 



Both arguments can be vectors, matrices, arrays, or higher- 
dimensional arrays. If either argument is a scalar or a 
1-element vector, it is extended so that its dimensions match 
the dimensions of the other argument. 

Both f and g can be any dyadic scalar function as long as both 
are of the same type, that is, both arithmetic, both logical, 
and so on. 



Definition 



Obtains the common algebraic matrix product, and also extends 
this capability to other arithmetic operations and other array 
dimensions. 

You can also specify an inner product in which an operation other 
than multiplication is performed. It is possible to locate 
values containing specific characters by this method or to search 
for a row of one array in which all the elements are equal to 
those in a column of another array. 

The two arguments, say A and B, must conform to certain rules to 
be used in an inner product operation. The two arguments con- 
form if any of the following is true: 

1. ^ or B is a scalar. 

2. Results of -lfpi4 and -IfpB are equal. 

3. Either -lfp4 or -IfpB equals 1. 

If the third characteristic is the case, then the corresponding 
argument is extended so that the arguments have equal lengths 
along the specified coordinate. The basic test for conformability 
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is whether or not the length of the last dimension of the left 
argument matches the length of the first dimension of the right 
argument. The dimensions of the result can then be considered 
all dimensions of A except the last, catenated to all dimensions 
of B except the first. 

In Table 3-9, the letters have the following meaning: 



CD ,E ,F 



I ,J 



is a primitive function. 

is a primitive function. 

is an argument. 

is an argument. 

is the result. 

are the respective shapes of the 
arguments. 

are indices. 



Note that when one or both of the arguments are scalar the shape 
of the arguments need not conform to any rules. 



Table 3-9 
Inner Product Description 



Definition of 




Shape 




Result 


Z^Af.gB 


pA 




pB 


p2 


Z<-f/AgB 


scalar 




scalar 


scalar 


Z^f/AgB 


scalar 




E 


scalar 


Z^f/AgB 


D 




scalar 


scalar 


ZLll^f/AgBL',11 


scalar 




E F 


F 


ZLll<-f/AlI;:\gB 


C D 




scalar 


C 


ZZll^f/AgBL;Il 


D 




D F 


F 


Z[J]^f//4[J;]gB 


C B 




D 


C 


ZLl;Jl<-f/ALl;2gBL ;J] 


C D 




D F 


C F 



3-71 



APL FUNCTIONS AND OPERATORS 



Examples 



12 3 



4 I' 
1 2 3 
14 32 
14 
12 



At ♦ XB 

( I 3 ) »■ , X \ 3 
2 6t».iA 



Af , XftjA 

14 32 

32 77 

[I i-- >i i- 4 3 f ' o >•< k; t' w o s x' ;■; r- b h 

OHE 
TWO 
S 1" X 
TEN 

f >' 

4 3 

V <•• < s 1 ;■( ' 

3 

KA , =::V 
10 



Related Operators 

Outer Product, Section 3.5.2 



3-72 



APL FUNCTIONS AND OPERATORS 

3.5.2 o.for.SO.f- The Outer Product Operator 

Format 

dyadic 

Argument Types 

Both arguments can be any array. The <> symbol is the jot char- 
acter, not the circle. 

The f is any dyadic scalar function. The period (.) is the 
connector between the jot and the function. 

Definition 

Specifies an operation to be performed by every element of one 
array on every element of another array. For example, in the 
expression R-^A.tB, R is any array that results from applying f to 
every pair of elements of A and B. The shape of R is the dimen- 
sions of A catenated to the dimensions of B, or (pi4),pB. Unlike 
inner product, outer product performs only one operation. 

Table 3-10 describes the results of using a variety of arrays. 

The letters have the following meaning: 

f is a primitive function. 

g is a primitive function. 

A is an argument. 

B is an argument. 

C,D,E,F are the respective shapes of the 

arguments. 

I,J,K,L are indices. 

Z is the result. 
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Table 3-10 
Outer Product Description 



Definition of 




Shape 




Result 


Z^i4° .gS 


pA 




pB 


p2 




Z^AgB 


scalar 




scalar 


scalar 


ZlIl^AgBLll 


scalar 




E 


E 




ZLll^ALllgB 


D 




scalar 


D 




ZLliJl^ALllgBLJl 


D 




E 


D 


E 


ZLl;j:[<-AgBlI;Jl 


scalar 




E F 


E 


F 


ZLliJl^ALliJlgB 


C D 




scalar 


C 


D 


ZLl;J;Kl^ALllgBLJ;Kl 


D 




E F 


D 


E F 


ZLI; J ;n<-AlI; j:\gBlKl 


C D 




E 


C 


D E 


ZLl',J;K',Ll^AlI;JlgBLK;Ll 


C D 




E F 


C 


D E F 



Examples 



1 2 3<>.^2 3 4 
2 3 4 5 
4 6 e 10 
6 9 12 IS 

f-^i-1 2 3 2 2 1 

( \3)« ♦-^^ 
10 1 
1 1 1 
10 



2 3 1 



*•/< \3)« .^^^^^^ 



fjTHERiii: are: 2 oi'<E;:-:iv 3 twos^ ani:- j three xh a 



Related Operators 

Inner Product, Section 3.5.1 
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3.5.3 f / - The Reduction Operator 

Format 

monadic 

Argument Types 

The argument is a scalar, a vector or one coordinate of an array. 
The f can be any scalar dyadic function. 

Definition 

Specifies that an operation is to be used to combine the elements 
of a vector or elements along a specified dimension of an array. 
The result of reducing any vector is a scalar value. 

The result of reducing an array has a rank that is one less than 
the rank of the original array. Thus, the reduction of a matrix 
yields a vector. To specify a coordinate, include it within 
square brackets. (The coordinate is dependent upon the index 
origin. Section 4.2.11.) The default is the highest coordinate. 
The special symbol to specify the first coordinate is / (.CS). 

If the argument is an empty vector, then the result of a reduc- 
tion is the identity element of the operator, if one exists. 
Table 3-11 lists the identity elements for scalar dyadic functions 



Table 3-11 
Identity Elements 



Dyadic Operator 


Symbol 


Identity Element 


Plus 


+ 





Minus 


- 





Times 


X 


1 


Divide 


T 


1 


Power 


* 


1 


Residue 


1 





Maximum 


r 


1.701411835E38 


Minimum 


L 


1.701411835E38 


Logarithm 


® 


none 


Combination 


! 


1 


Circle 


o 


none 


And 


& 


1 


Or 


V 





Nand 


7^ 


none 


Nor 


V 


none 


Less 


< 





Not Greater 


^ 


1 


Equal to 


= 


1 


Not Less 


> 


1 


Greater 


> 





Not Equal 


7i 
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Examples 



12 3 4 5 6 

J. / ;•; 

21 

X / ■< 
720 



X 










^■/Z 7 


8 




20 










y/l 6 


.., 




14 










■■/I 6 


7 














flSAME 


AS 


1-.' 



7 

X / \ 
1 

Of.Af.2 4fl6 
J. 2 3 4 
5 6 12 

«/i:;2i« 

10 14 

:/i::i::i« 

6 B 4 6 



Related Operators 

Scan, Section 3.5.4 
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3. 5.4 f\ - The Scan Operator 

Format 

monadic 

Argument Types 

The argument can be a scalar, a vector, or one coordinate of an 
array. 

The f is any scalar dyadic function. 

Definition 

Returns partial results in calculating the reduction of an array. 
The shape of the result of a scan is the same as the shape of the 
original vector. The first element of the result is always iden- 
tical to the first element of the original vector. The last 
element is equal to a reduction of the entire original vector. 
For example : 

•t\3 4 S 
3 7 12 

If the argument is a null vector, then the result of the scan is 
a null vector. 

You can also specify a scan for one particular coordinate of a 
multidimensional array. You specify the coordinate to be scanned 
by including a bracketed number with the function. The syntax is 
the same as that of the reduction function. If you omit the 
coordinate within brackets, APL scans the last coordinate of the 
array. You can specify a scan on the first coordinate by using 
the symbol \ (.CB), which is formed by overstriking the scan 
(backslash) with the minus sign. 

If the dyadic function specified with scan is associative (for 
example, + or x) APL performs the scan in a way that is different 
from the conventional scan, in order to increase efficiency by 
reducing the number of operations. The definition of R-^-fXA is 
equal to RLll=f/IiA as follows: 

i?CJ]=/?[J-l]f^CJ]FOi? lelipA 

This definition requires fewer operations than the traditional 
scan. The result of an associative operation of this kind may 
differ slightly from the nonassociative approach and should be 
used carefully if the results require a high degree of precision. 
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Examples 



A 

1 •■■• :i. o o o i. , o o o o o o o o o k^ ■■■• 1 6 

{• \ (■>, 
1000000 :l. »000000000i^""1.6 





4 8 

v\0 1 



:i. :l. :l. 



x\i7 
1 2 6 24 :L20 720 5040 





Oi-Af. 


2 3ri 


:l. 


2 3 




4 


5 6 




:l. 


3 


6 


4 


9 


15 




*\i:::i. 


;;i ^•' 


5 


2 3 
7 9 






*■ \ i:; 2 


'::iA 


:l. 


3 


6 


4 


9 


I'S 


J. 
b 


2 3 
7 9 





Related Operators 

Reduction, Section 3.5.3 
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CHAPTER 4 
APL SYSTEM COMMUNICATION 



4 . 1 INTRODUCTION 

There are a variety of ways in which you can communicate with the APL 
system to change parameters, determine hardware or operational char- 
acteristics, and modify processing methods. The APL system commands 
in Chapter 5 facilitate many of these system operations. The ele- 
ments in Chapter 4 that aid system communication are: 

system variables - They are similar to ordinary variables but are 
distinguished by special names that begin with a quad character, 
for example, ULX . 

system functions - They allow you to interact with APL by speci- 
fying distinguished names beginning with a quad character, for 
example, QCM. 

Section 4.2 describes system variables and Section 4.3 describes 
system functions. 



4.2 SYSTEM VARIABLES 



APL system variables allow you to perform such operations as the 
following: 

1. Set the index origin and relative fuzz 

2. Change the output precision and line width 

3. Specify an operation to be performed when the workspace is 
activated 

4. Save the active workspace automatically after editing 

The syntax of APL system variables is similar to ordinary variables in 
that you can use both types of variables in any language expression or 
function. APL system variables have distinguished names; they begin 
with a quad character (D) . They differ from ordinary variables 
because of their special significance to the system. 

APL system variables cannot be used as names for user-defined func- 
tions. Also, you cannot copy, erase, or collect them in a group. 
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The 25 system variables described in this chapter serve as an inter- 
face between APL and the operating system you are using. The work- 
space and the APL processor can each use values specified by the other 
as appropriate to the particular operation being performed. The value 
of a system variable being used in a workspace can sometimes be dif- 
ferent from the value last specified by the user of the workspace. 

System variables fall into two categories: 

1. System variables to which you can assign a value. These 

variables retain the value until you override it with another 
value or clear the workspace. You can save the value with 
the workspace, and you can also localize them in a function 
definition. These system variables do have default values. 
The following system variables are in this category: 



UAUS 


Section 


4.2.5 


OCT 


Section 


4.2.7 


UERROR 


Section 


4.2.9 


UGAG 


Section 


4.2.10 


UIO 


Section 


4.2.11 


mmmwmmmmih 


iHflfj^glpf; 


iC(gf?iit0^ 


DPP 


Section 


'T:T:t5 


UPW 


Section 


4.2.16 


URL 


Section 


4.2.17 


USF 


Section 


4.2.18 


UTIMELIMIT 


Section 


4.2.19 


i^^Biiipiiiiii 


■■■^■IBI 


■■■M 



2. System variables that have values you cannot change. If you 
assign a value to this type of variable, you will not receive 
an error; however, the assignment will have no effect. The 
following system variables are in this category: 



UAI 


Section 


4. 


.2. 


.1 


UALPHA 


Section 


4, 


.2, 


.2 


UALPEAU 


Section 


4, 


.2, 


.3 


UASCII 


Section 


4, 


.2. 


.4 


UAV 


Section 


4, 


.2, 


.6 


UCTRL 


Section 


4, 


,2. 


.8 


ULC 


Section 


4, 


.2. 


.12 


UNUM 


Section 


4, 


.2, 


.14 


UTIMEOUT 


Section 


4, 


.2, 


.20 


UTS 


Section 


4, 


.2, 


.22 


UTT 


Section 


4, 


.2, 


.23 


UUL 


Section 


4, 


.2. 


.24 


UWA 


Section 


4. 


.2. 


.25 



4.2.1 D^J - Storing Account Information 

The UAI (account information) system variable stores the following 
account information during a work session: 

1. User identification (for the project-programmer number 
[PROJ,PROG] this is PROG+PROJx2*18) 

2. Computer time (CPU time) used during the current APL session 
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3. Connect time used during the current APL session 

4. Keying time (time during which the keyboard is unlocked) used 
during the current APL session 

All times are expressed in milliseconds. 

For example : 

104870B 1235 440967 382458 



4.2.2 UALPHA - Alphabetic Characters 

The UALPHA system variable is a subset of the UAV system variable. 
Section 4.2.6. The value contained in UALFEA is a vector of the 27 
alphabetic characters A and A through Z. 

For example: 

rjAI.-l=HA 

A A B c' r> i-i: F Cv n :i: ...i i< l„ m h o i-- « rt i:> r- u v w ;c r z 



4.2.3 UALPEAU - Underlined Alphabetics 

The UALPEAU system variable is a subset of the UAV system variable. 
Section 4.2.6. The value contained in UALPEAU is a vector of the 27 
underlined characters A and A through Z. 

For example: 

|:;|AI...PHAU 

ili 6 S! £ i!!! !il! !::! S !::! I h^ K !:r M y Q !::: ??! lii; 5s I y Ix! w il^ !](; ^ 

D'^^V I |.'.|AI...PIIAU 

481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 
496 497 498 499 500 501 502 503 504 505 506 507 



4.2.4 UASCII - ASCII Character Set 

The UASCII system variable contains 128 ASCII characters. This dis- 
tinguished variable is designed primarily for use with ASCII files, 
as an easy way to output arbitrary ASCII codes to those files while 
using the APL character set. The first 32 characters of UASCII are 
the control characters in UCTRL , Section 4.2.8. The rest are pure 
ASCII, not translatable by APL. 

UASCII is a subset of UAV. The indices into UAV that contain UASCII 
are UAV12S1'] through Dil7[288] and D^FLSSl] through n^7[476]. 

UASCII is intended for use with output functions, especially output to 
the terminal. It accepts a list of numbers that it translates into 
ASCII codes for transmission. It does not go through the usual trans- 
lation from APL 9-bit to ASCII. 
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When you write to an ASCII sequential file (Section 7.5.1) using 
UASCII, you can output the full range of ASCII characters. The 
following example writes seven ASCII characters to an ASCII sequential 
file while in APL mode. The APL equivalents of these characters print 
during output. Once back at operating system command level, you can 
access the ASCII characters. 



For example: 



1.2 



|;;|ASS ' TUTS /AS « 

[;i Asc :i: ;i: 136 9 3S ^ 39 y A3 , 65 ^ 95 ^ 961B 1 2 



n<"i-^;; 1.2 

) MOH 
MONHiTOR ♦ 

(»TY THIS. A AS 

#%8;*0'\... 

@ 

& 

Table 4-1 contains the decimal indices and octal values of UASCII. 



Table 4-1 
The ASCII Character Set 

UASCII (UIO^I) 



Index 


ASCII Char 


Octal Value 


1 


NUL 


000 


2 


SOH 


001 


3 


STX 


002 


4 


ETX 


003 


5 


EOT 


004 


6 


ENQ 


005 


7 


ACK 


006 


8 


BEL 


007 


9 


BS 


010 


10 


HT 


Oil 


11 


LF 


012 


12 


VT 


013 


13 


FF 


014 


14 


CR 


015 


15 


SO 


016 


16 


SI 


017 


17 


DLE 


020 


18 


DCl 


021 


19 


DC2 


022 


20 


DC3 


023 


21 


DC4 


024 


22 


NAK 


025 


23 


SYN 


026 


24 


ETB 


027 


25 


CAN 


030 


26 


EM 


031 


27 


SUB 


032 
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Table 4-1 (Cont.) 
The ASCII Character Set 

DASCII iUlO^l) 



Index 


ASCII Char 


Octal Value 


28 


ESC 


033 


29 


FS 


034 


30 


GS 


035 


31 


RS 


036 


32 


US 


037 


33 


space 


040 


34 


1 


041 


35 


II 


042 


36 


# 


043 


37 


$ 


044 


38 


% 


045 


39 


& 


046 


40 


' (apostrophe) 


047 


41 


( 


050 


42 


) 


051 


43 


* 


052 


44 


+ 


053 


45 


/ 


054 


46 


- 


055 


47 


, 


056 


48 


/ 


057 


49 





060 


50 


1 


061 


51 


2 


062 


52 


3 


063 


53 


4 


064 


54 


5 


065 


55 


6 


066 


56 


7 


067 


57 


8 


070 


58 


9 


071 


59 


; 


072 


60 


7 


073 


61 


< 


074 


62 


= 


075 


63 


> 


076 


64 


•p 


077 


65 


@ 


100 


66 


A 


101 


67 


B 


102 


68 


C 


103 


69 


D 


104 


70 


E 


105 


71 


F 


106 


72 


G 


107 


73 


H 


110 


74 


I 


111 


75 


J 


112 


76 


K 


113 


77 


L 


114 


78 


M 


115 


79 


N 


116 


80 





117 


81 


P 


120 
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Table 4-1 (Cont.) 
The ASCII Character Set 

DASCII (DJ^^l) 



Index 


ASCII Char 


Octal Value 


82 


Q 


121 


83 


R 


122 


84 


S 


123 


85 


T 


124 


86 


U 


125 


87 


V 


126 


88 


W 


127 


89 


X 


130 


90 


Y 


131 


91 


Z 


132 


92 


[ 


133 


93 


\ 


134 


94 


] 


135 


95 


•^ (uparrow) 


136 


96 


(underscore) 


137 


97 


^ (grave) 


140 


98 


a 


141 


99 


b 


142 


100 


c 


143 


101 


d 


144 


102 


e 


145 


103 


f 


146 


104 


g 


147 


105 


h 


150 


106 


i 


151 


107 


J 


152 


108 


k 


153 


109 


1 


154 


110 


m 


155 


111 


n 


156 


112 


o 


157 


113 


P 


160 


114 


q 


161 


115 


r 


162 


116 


s 


163 


117 


t 


164 


118 


u 


165 


119 


V 


166 


120 


w 


167 


121 


X 


170 


122 


Y 


171 


123 


z 


172 


124 


{ 


173 


125 


1 
1 


174 


126 


} 


175 


127 


~ 


176 


128 


DEL 


177 



[M5CJJ[124] through 
on a VT05 or VT52 . 



[127] print differently on other terminals such as 
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4.2.5 UAUS - Saving a Workspace Automatically 

The UAUS (automatic save) system variable activates a special feature 
that allows you to save the currently active workspace automatically 
at periodic intervals. Workspace backup is often critical when you 
are performing an extensive amount of function editing and debugging 
or typing a large table of values. Normally, you would stop editing 
and issue the appropriate APL commands (Chapter 5) to save the work- 
space on disk to ensure that a system crash does not destroy the cur- 
rent workspace. If UAUS is set to 1, APL automatically saves the 
workspace on disk every time a function is closed or a quad-input 
request is sent to the terminal. This ensures that you will probably 
have to reenter only a small amount of input in the event of a system 
crash. 

The default value for UAUS in a clear workspace is installation de- 
pendent and can be changed by the System Manager. APL saves the value 
of UAUS with the workspace, and you can localize it in the same manner 
as UIO and several other variables. 

When saving a workspace, UAUS creates a disk file and assigns a name 
to it in the format: 



XNNWWW . TMP 



where 



X is 4, if the job number divided by 100 equals 0. 

is 5, if the job number divided by 100 equals 1, and so on. 

NN is the job number modulo 100. 

WWW is the first three characters of the current workspace name, 

TMP is extension or filetype. 

For example, if the job number is 79 and the workspace name is TESTS, 
then the temporary filename will be A79TES .TMP. If the job number is 
179, the temporary file will be B79TES .TMP. 

If the system crashes and is reloaded, you can verify that a temporary 
disk file exists for the workspace by issuing a )LIB command. For 
example : 

) I... :i:b f( , TMP 
t> s K ♦ 

A79TI:::S/rMF=- 

After APL displays the sign-on message, you can load the backup file 
as the active workspace by issuing a )LOAD command (Section 5.2.4). 

) I.. O A t< A 7 9 T' ll." S ^ T M ¥■■ 

s> A V E D 9tA9t 5 9 2 - -^ ^-^ '•■• - 7 9 '5 •'•■ 
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APL prints the )LOAD message. The name of the active workspace is now 
the name that the workspace had before the backup was performed, not 
the name of the temporary file. 

) W S X I' 

TESTS i,:4 5.204:;i 

After completing the editing of a function or entering data you should 
explicitly save the active workspace and delete the temporary backup 
on disk. 

APL deletes a .TMP file that it has written when any one of the follow- 
ing conditions occurs: 

1. A )SAVE has been completed successfully. 

2. An )OFF, ) CONTINUE, )CALL, or )RUN command is executed. 
APL intends to write a new .TMP file with a different name. 

For example: 

OAUS<i..J. 

)ws.i:x:i ABC 

WAS CLEAR WS 

111 '^^^2^x7:1.3 

i:2:j B^A.:.<f,e 
[:3;] V 

i-i I:-: Hi; E A f- 1... w I-: n: t i;;: *i; t i-i e ^ t m i"- i-' :i; i._ ii;: 

)l.. .TB n ^ TMP 
DSK ♦ 
A:|. (:jAX:<C\ TMP 

)wsn:.B xr^. 
w A s A B V. I" 4 y 2 4 ;] 

i::3::i » 
i::4 3 V 

fl I •) E I-: Ei; (^ I"- 1... w I-: X r' Ki; s t h lii; h b. w ,. t' m f- f ;i: i... i;:: 
) L. :i: B )if ^ T- M I"- 
t" s K ♦ 



4 .2.6 UAV - Atomic Vector 

The UAV (atomic vector) system variable contains a vector of every 
character in APL. Table 4-2 lists the characters with their positions 
in the vector. Note that the positions are based on an index origin 
of 1. In Table 4-2 characters that are normally non-printable are 
output as , a squish quad. 
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Table 4-2 
The Atomic Vector UAV (UIO^l) 



UAVLl 


Symbol 


TTY Set 


Name 


1 through 16 


Q 


.SQ 


squish quad 


17 


1 


! 


factorial 


18 


4> 


.RV 


reversal 


19 


^ 


.TR 


transpose 


20 


I 


.IB 


I -Beam 


21 


H 


.QQ 


quote quad 


22 


® 


.LG 


logarithm 


23 


f< 


.NN 


Nand 


24 


V 


.NR 


Nor 


25 


R 


II 


Comment (lamp) 


26 


A 


.GU 


grade up 


27 


t 


.GD 


grade down 


28 


e 


.CR 


circle (rotate) 


29 


/ 


.CS 


back scan 


30 


\ 


.CB 


back expansion 


31 


D 


.SQ 


squish quad 


32 


¥ 


.PD 


protected del 


33 





.QD 


quad del 


34 





.IQ 


input quad 


35 


a 


.OQ 


output quad 


36 


a 


.DQ 


divide quad (domino) 


37 


$ 


$ 


format (dollar) 


38 


cc 


.FI 


fix 


39 


± 


.XQ 


execute 


40 


w 


.FM 


format 


41 through 46 


D 


• SQ 


squish quad 


47 




.DD 


dieresis 


48 


< 


< 


less than 


49 


<. 


.LE 


less than or equal 


50 


> 


.GE 


greater than or equal 


51 


> 


> 


greater than 


52 


9 


? 


question (roll, deal) 


53 


W 


.OM 


omega 


54 


e 


.EP 


epsilon 


55 


P 


.RO 


rho 


56 


f 


/\ 


take 


57 


4- 


.DA 


drop (down arrow) 


58 


1 


.10 


iota 


59 


a 


.AL 


alpha 


60 




.CE 


ceiling 


61 




.FL 


floor 


62 




( 


left parenthesis 


63 




) 


right parenthesis 


64 




[ 


left square bracket 


65 




] 


right square bracket 


66 


c 


.RU 


right union 


67 


z> 


.LU 


left union 


68 


U 


.UU 


up union 


69 




.US 


underscore 


70 through 7 2 


D 


.SQ 


squish quad 


73 


-«- 


- 


left arrow (assignment) 


74 


->- 


.GO 


right arrow (branch) 


75 


D 


.BX 


quad (box) 


76 


X 


.NE 


not equal 


77 


= 


= 


equal 


78 


n 


.DU 


down union 


79 


1 


.DE 


decode 
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Table 4-2 (Cont.) 
The Atomic Vector UAV (UI0<-1) 



CMF[] 


Symbol 


TTY Set 


Name 




80 


A 


& 


and 




81 


V 


.OR 


or 




82 


~ 


.NT 


not 




83 


/ 


/ 


reduce 




84 


\ 


\ 


expand 




85 


* 


* 


exponentiate 


(star) 


86 


X 


# 


multiply 




87 


T 


% 


divide 




88 


+ 


+ 


add 




89 


- 


- 


subtract 




90 


o 


.LO 


circle (large o) 


91 


1 


.AB 


residue (absolute) 


92 


; 


1 


semicolon 




93 


5 


t 


comma 




94 


O 


.SO 


jot (small o] 




95 


T 


.EN 


encode 




96 


V 


.DL 


del 




97 




: 


colon 




98 


t 


1 


quote 




99 


(none) 


(backspace) 


for internal 


use 


100 


(none) 


(line feed) 


for internal 


use 


101 


(none) 


(double line 
feed) 


for internal 


use 


102 


(none) 


(carriage 
return) 


for internal 


use 


103 


(none) 


(null) 


for internal 


use 


104 


(none) 


(space) 


for internal 


use 


105 


(none) 


(escape) 


for internal 


use 


106 


(none) 


(formfeed) 


for internal 


use 


107 


(none) 


(tab) 


for internal 


use 


108 





.SQ 


squish quad 




109 


. 


. 


period 




110 




.NG 


negation 




111 


D 


.SQ 


squish quad 




112 


(none) 


(at @) 


for internal 


use 


113 


(none) 


(left 
bracket) 


for internal 


use 


114 


H 


.LK 


left tack 




115 


(none) 


(right 
bracket) 


for internal 


use 


116 


(none) 


(uparrow) 


for internal 


use 


117 


(none) 


(left arrow) 


for internal 


use 


118 





.DM 


diamond 




119 


{ 


.LB 


left curly brace | 


120 


H 


.RK 


right tack 




121 


} 


• RB 


right curly brace | 


122 


(none) 


(tilde) 


for internal 


use 


123 


(none) 


(delete) 


for internal 


use 


124 through 256 


D 


.SQ 


squish quad 




257 


UCTRLL 11 


.BXCTRLCl] 


null (NUL) 




258 


UCTRLL 21 


.BXCTRLC2] 


start of heading (SOH) 


259 


DCTRLL 31 


.BXCTRLE3] 


start of text (STX) 


260 


UCTRLL 1^1 


.BXCTRLE4] 


end of text 


(ETX) 


261 


UCTRLL 5 1 


.BXCTRLE5] 


end of transmission | 








(EOT) 




262 


UCTRLL 6 1 


.BXCTRLC6 3 


enquiry (ENQ) 




263 


UCTRLL7 1 


.BXCTRLE7] 


acknowledge 


:ack) 
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Table 4-2 (Cont.) 
The Atomic Vector UAV (UIO^I) 



UAVLl 


Symbol 


TTY Set 


Name 


264 


UCTRLL81 


.BXCTRLC8] 


bell (BEL) 


265 


UCTRLL9 1 


.BXCTRLC9] 


backspace (BS) 


266 


nC!Z'i?LClO] 


.BXCTRLCIO] 


horizonal tabulation 
(HT) 


267 


UCTRLL 112 


.BXCTRLCll] 


line feed (LF) 


268 


nCTRLL 121 


.BXCTRL[12] 


vertical tab (VT) 


269 


nCTRLLlSl 


.BXCTRLC13] 


form feed (FF) 


270 


UCTRLL lUl 


.BXCTRLC14] 


carriage return (CR) 


271 


UCTRLL 15 1 


.BXCTRLC15] 


shift out (SO) 


272 


UCTRLLl&l 


.BXCTRLC16] 


shift in (SI) 


273 


UCTRLLnl 


.BXCTRLC17] 


data link escape (DLE) 


274 


UCTRLL 181 


.BXCTRLE18] 


device control 1 (DCl) 


275 


aC!Z'i?LCl9] 


.BXCTRLC19] 


device control 2 (DC2) 


276 


nC!Z'i?LC20] 


.BXCTRLC20] 


device control 3 (DC3) 


277 


UCTRLL 211 


.BXCTRLC21] 


device control 4 (DC4) 


278 


UCTRLL221 


.BXCTRLC22] 


negative acknowledge 
(NAK) 


279 


UCTRLL 231 


.BXCTRLC23] 


synchronous idle (SYN) 


280 


DCTRLL 2^1 


.BXCTRLC24] 


end of transmission 
block (ETB) 


281 


UCTRLL2 5 1 


.BXCTRLC25] 


cancel (CAN) 


282 


UCTRLL 2&1 


.BXCTRLC26] 


end of medium (EM) 


283 


UCTRLL 271 


.BXCTRLE27] 


substitute (SUB) 


284 


UCTRLL 2 81 


.BXCTRLC28] 


escape (ESC) 


285 


UCTRLL 29 1 


.BXCTRLC29] 


file separator (FS) 


286 


UCTRLL 30 1 


.BXCTRLC30 3 


group separator (GS) 


287 


UCTRLL 311 


.BXCTRL[31] 


record separator (RS) 


288 


UCTRLL 321 


.BXCTRLC32] 


unit separator (US) 


289 through 304 


D 


.SQ 


squish quad 


305 








zero 


306 


1 


1 


one 


307 


2 


2 


two 


308 


3 


3 


three 


309 


4 


4 


four 


310 


5 


5 


five 


311 


6 


6 


six 


312 


7 


7 


seven 


313 


8 


8 


eight 


314 


9 


9 


nine 


315 through 352 


D 


.SQ 


squish quad 


353 


A 


.LD 


delta 


354 


A 


A 


A 


355 


B 


B 


B 


356 


C 


C 


C 


357 


D 


D 


D 


358 


E 


E 


E 


359 


F 


F 


F 


360 


G 


G 


G 


361 


H 


H 


H 


362 


I 


I 


I 


363 


J 


J 


J 


364 


K 


K 


K 


365 


L 


L 


L 


366 


M 


M 


M 


367 


N 


N 


N 


368 











369 


P 


P 


P 
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Table 4-2 (Cont.) 
The Atomic Vector UAV (QlO^l) 



DAVLl 


Symbol 


TTY Set 


Name 


370 


Q 


Q 


Q 


371 


B 


R 


R 


372 


S 


S 


S 


373 


T 


T 


T 


374 


U 


U 


U 


375 


V 


V 


V 


376 


W 


W 


W 


377 


X 


X 


X 


378 


Y 


Y 


Y 


379 


Z 


Z 


Z 


380 


Q 


• SQ 


squish quad 


381 


D/45CJJE33] 


.BXASCIIL33] 


space 


382 


UASCIIl^^^ 


.BXASCIIC34] 


exclamation point ( ! ) 


383 


n^-SCJJ[35] 


.BXASCIIC35: 


double quote (") 


384 


D45CJJC36] 


.BXASCII[36] 


number sign (#) 


385 


UASCIIl^ll, 


.BXASCIIC37] 


dollar sign ($) 


386 


n/15CJJC38] 


.BXASCII[38] 


percent (%) 


387 


D^5(7JJ[39] 


.BXASCIIC39] 


ampersand (&) 


388 


UASCIIl^Q^ 


.BXASCIIC40] 


apostrophe ( ' ) 


389 


UASCII{.^1'\ 


.BXASCIIC41] 


left parenthesis (() 


390 


D4-SCJJC42] 


.BXASCIIE42] 


right parenthesis () ) 


391 


D4-S'CJ-r[43] 


.BXASCIIC43] 


asterisk (*) 


392 


ni45CJlC44] 


.BXASCIIC44] 


plus (+) 


393 


UASCIIlhb^ 


.BXASCIIE45] 


comma ( , ) 


394 


UASCIIl^&l 


.BXASCIIC463 


hyphen (-) 


395 


Di45CIJ[47] 


.BXASCIIC47] 


period ( . ) 


396 


UASClUhQl 


.BXASCIIC48] 


slash (/) 


397 


D^5CIJ[49] 


.BXASCIIC49] 


zero (0) 


398 


n45CJJ[50] 


.BXASCIIC50] 


one (1) 


399 


UASCIIlbl'l 


.BXASCIIC51] 


two (2) 


400 


UASCIIIS2'] 


.BXASCII[52] 


three (3) 


401 


UASCIIlb2,^ 


.BXASCIIC53] 


four (4) 


402 


Di45CJI[5L^] 


.BXASCIIC54] 


five (5) 


403 


D^^CJi"[55] 


.BXASCIIE55] 


six (6) 


404 


UASCIIlb^l 


.BXASCIIC56] 


seven (7) 


405 


UASCIIlbl'\ 


.BXASCIIC57] 


eight (8) 


406 


n.46'CJJC58] 


.BXASCIIC58] 


nine (9) 


407 


a^5(7JJC59] 


.BXASCIIE59] 


colon ( : ) 


408 


UASCIIl^Q^ 


.BXASCIIE60] 


semicolon ( ; ) 


409 


UASCIIl&ll 


.BXASCIIC61] 


less than (<) 


410 


n^5CIJ[62] 


.BXASCII[62] 


equal (=) 


411 


n^5CIJ[63] 


.BXASCIIE63] 


greater than (>) 


412 


n^5Ci"J[64] 


.BXASCIIC64] 


question mark (?) 


413 


UASCIIl^^l 


.BXASCIIC65 3 


at sign (@) 


414 


D^^Ci"J[66] 


.BXASCIIC66] 


A 


415 


UASCIIl^ll 


.BXASCIIC67] 


B 


416 


UASCIIl^Ql 


.BXASCIIE68] 


C 


417 


n.4<SCi"J[69] 


.BXASCIIC69] 


D 


418 


UASCIIllQl 


.BXASCIIC70] 


E 


419 


UASCIIlll^ 


.BXASCIIC71] 


F 


420 


UASCIIll2:\ 


.BXASCIIC72] 


G 


421 


n.45CJJ[73] 


.BXASCII[73] 


H 


422 


UASCIIll^l 


.BXASCIIE74] 


I 


423 


UASCIIllbl 


.BXASCIIC75] 


J 


424 


n^5CJJC76] 


.BXASCIIE76] 


K 


425 


UAsciiiii:^ 


.BXASCIIE77] 


L 


426 


UASCIIllQ^ 


.BXASCIIE78] 


M 
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Table 4-2 (Cont.) 
The Atomic Vector UAV (UIO^l) 



UAVLl 


Symbol 


TTY Set 


Name 




427 


UAsciin 91 


.BXASCIIE79] 


N 




428 


UASCIIL 801 


.BXASCIIC80] 







429 


UASCIIL Qll 


.BXASCIIC81] 


P 




430 


UASCIIL 821 


.BXASCIIC82] 


Q 




431 


D^^CIJC83] 


.BXASCIIC83] 


R 




432 


HAS CI 118^1 


.BXASCIIC84] 


S 




433 


UASCIIL 851 


.BXASCIIC85] 


T 




434 


UASCIIL 861 


.BXASCIIE86] 


U 




435 


UASCIIL871 


.BXASCIIC87] 


V 




436 


UASCIIL881 


.BXASCIIC88] 


W 




437 


UASCIIL 891 


.BXASCIIE89] 


X 




438 


UASCIIL901 


.BXASCIIC90] 


Y 




439 


UASCIIL911 


.BXASCIIC91] 


Z 




440 


UASCIIL921 


.BXASCIIC92] 


left square bracket 


([) 


441 


UASCIIL 9 31 


.BXASCIIE93] 


backslash (\) 




442 


UASCIlL9i^l 


.BXASCIIC94] 


right square bracket 
(]) 




443 


UASCIIL951 


.BXASCIIC95 3 


up arrow (^) 




444 


UASCIIL961 


.BXASCIIC96] 


underscore (_) 




445 


UASCIIL971 


.BXASCIIE97] 


grave ( "" ) 




446 


n^-SCJ"JC98] 


.BXASCIIC98] 


a 




447 


UASCIIL991 


.BXASCIIC99] 


b 




448 


UASCIILlOOl 


.BXASCIICIOO] 


c 




449 


UASCIILlOll 


.BXASCIICIOI] 


d 




450 


UASCIIL1021 


.BXASCIIC102] 


e 




451 


UASCIILlQSl 


.BXASCIIC103] 


f 




452 


UASCIILlOOl 


.BXASCIIC104] 


g 




453 


UASCIIL1051 


.BXASCIIC105] 


h 




454 


n^5CJJ[106] 


.BXASCIIC106] 


i 




455 


UASCIILlOll 


.BXASCIIC107] 


J 




456 


UASCIIL1081 


.BXASCIIC108] 


k 




457 


D^5CJJC10 9] 


.BXASCIIC109] 


1 




458 


D^^CJJCllO] 


.BXASCIICIIO] 


m 




459 


UASCIILllll 


.BXASCIICIII] 


n 




460 


UASCIIL1121 


.BXASCIIC112] 


o 




461 


UASCIIL1131 


.BXASCIIC113] 


P 




462 


UASCIILllll 


.BXASCIIC114] 


q 




463 


UASCIIL1151 


.BXASCIIC115] 


r 




464 


UASCiiLiiei 


.BXASCII[116] 


s 




465 


UASCIILllll 


.BXASCIIC117] 


t 




466 


UASCIIL1181 


.BXASCIIC118] 


u 




467 


UASCIIL1191 


.BXASCIIE119] 


V 




468 


D^5CJrCi2 0] 


.BXASCIIC12 3 


w 




469 


UASCIIL1211 


.BXASCIIC121] 


X 




470 


UASCIIL1221 


.BXASCIIE122] 


y 




471 


UASCIIL1231 


.BXASCII[123] 


z 




472 


UASCIIL1201 


.BXASCIIC124] 


left brace ({) 




473 


UASCIIL1251 


.BXASCIIC125] 


vertical bar ( j ) 




474 


UASCIIL1261 


.BXASCIIC126] 


right brace (}) 




475 


UASCIIL1211 


.BXASCIIE127] 


tilde (~) 




476 


UASCIIL1281 


.BXASCIIC128] 


delete (DEL) 




477 through 480 


Q 


• SQ 


squish quad 




481 


A 


.Z@ 


underscored delta 




482 


A 


.ZA 


underscored A 




483 


B 


.ZB 


underscored B 




484 


C 


.ZC 


underscored C 




485 


D 


.ZD 


underscored D 
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Table 4-2 (Cont.) 
The Atomic Vector QAV (UlO^l) 



Q<4 7[] 


Symbol 


TTY SET 


Name 


486 


K 


.ZE 


underscored E 


487 


F 


.ZF 


underscored F 


488 


G 


.ZG 


underscored G 


489 


H 


.ZH 


underscored H 


490 


I 


.ZI 


underscored I 


491 


J 


.ZJ 


underscored J 


492 


K 


.ZK 


underscored K 


493 


L 


.ZL 


underscored L 


494 


M 


.ZM 


underscored M 


495 


N 


.ZN 


underscored N 


496 





.ZO 


underscored 


497 


P 


.ZP 


underscored P 


498 


a 


.ZQ 


underscored Q 


499 


R 


.ZR 


underscored R 


500 


S 


.ZS 


underscored S 


501 


T 


.ZT 


underscored T 


502 


U 


.ZU 


underscored U 


503 


V 


.ZV 


underscored V 


504 


W 


• ZW 


underscored W 


505 


X 


.ZX 


underscored X 


506 


Y 


.ZY 


underscored Y 


507 


Z 


.ZZ 


underscored Z 


508 through 512 


D 


• SQ 


squish quad 



Subsets of UAV are: 



DA LP HA , 


Section 


4 


2 


2 


UALPHAU, 


Section 


4 


2 


3 


HAS CI I , 


Section 


4 


2 


4 


UCTRL , 


Section 


4 


2 


8 


UNUM, 


Section 


4 


2 


1 



4.2.7 UCT - Comparison Tolerance 

The UCT (comparison tolerance) system variable sets the degree of 
tolerance or relative fuzz (not absolute fuzz) to be applied in per- 
forming comparisons. The meaningful range of UCT values is through 
1E~8. The default value is 1E~13. 

You can specify UCT in conjunction with the following functions: 



Ceiling 

Floor 

Greater than 

Less than or equal to 

Equal to 

Greater than or equal to 

Less than 

Not equal to 
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The nCT value is saved when you save the active workspace. See the 
description of fuzz in Section 2.4.3. 



For example : 



[JCT 



4.2.8 nCTRL - Control Characters 



The UCTRL system variable is a subset of UAV (Section 4.2.6). It 
contains a vector of the 32 characters listed in Table 4-3. 



Table 4-3 

UCTRL (UIO^I) 



Index 


Character Name 


Octal Value 


1 


NUL(Null) 


000 


2 


SOH (Start of Heading) 


001 


3 


STX( Start of Text) 


002 


4 


ETX(End of Text) 


003 


5 


EOT (End of Transmission) 


004 


6 


ENQ (Enquiry) 


005 


7 


ACK (Acknowledge) 


006 


8 


BEL(Bell) 


007 


9 


BS (Backspace) 


010 


10 


HT(Horiz. Tabulation) 


Oil 


11 


LF(Line Feed) 


012 


12 


VT(Vert. Tabulation) 


013 


13 


FF(Form Feed) 


014 


14 


CR (Carriage Return) 


015 


15 


SO(Shift Out) 


016 


16 


SI (Shift In) 


017 


17 


DLE(Data Line Escape) 


020 


18 


DCl (Device Control 1) 


021 


19 


DC2 (Device Control 2) 


022 


20 


DC3 (Device Control 3) 


023 


21 


DC4 (Device Control 4) 


024 


22 


NAK (Negative Acknowledge) 


025 


23 


SYN( Synchronous Idle) 


026 


24 


ETB(End of Transmission Block) 


027 


25 


CAN (Cancel) 


030 


26 


EM (End of Medium) 


031 


27 


SUB (Substitute) 


032 


28 


ESC (Escape) 


033 


29 


FS(File Separator) 


034 


30 


GS (Group Separator) 


035 


31 


RS (Record Separator) 


036 


32 


US (Unit Separator) 


037 



Note that for any formatting-control character the internal code that 
appears in UCTRL is not the same as the internal code used by APLSF 
for that formatting-control character. 
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For example: 



f^ X 1i ti E ;-C O Mi: X G X M X S ± 

pAv^acTRi...L;i.4::i 

270 

nWHXLKn T ft KING THE P.KRST HALF OF 

flA CRI...F :i:s 



102 



4 .2.9 UERROR - Storing Error Messages 

The UERROR system variable contains text that identifies what error 
occurred and where it occurred. APL sets UERROR during immediate mode 
and function-definition mode as well as function-execution mode. 
UERROR contains one error at a time. When a new error occurs, the new 
message overwrites the old one. You can, however, localize UERROR 
within a function to save error information within the environment of 
a particular function. You can also set UERROR to contain your own 
message. In this way, you can clear UERROR by assigning a null string 
to it, UERROR' ' . 

The text that APL sets contains a character vector of variable-length 
lines, each delimited by a carriage return/line feed. The text has 
the following format: 

nn error message 

funcname [n] line containing the error caret pointing to symbol 
in error 
where 

nn error message is the number and text of the message. 

funcname is the name of the function in which the error 
occurred. 

[n] is the line number where the error occurred. 

For example : 

VABC J |:;|TRAF |;-|H::Ri-i:aR 
III 3 OTPtAFf. ' ..^ I...AX^ ' 

1:2 J l'^^-5 

[; 3 ;] I... (-u-f* \;\ B R !••; A i< ' c i-i 1;:; c i< k: r r o (■■■. m e s s a g i-i: • 

I" 4 "I ' i=': I-i: s i-J M e: a t l. :i: i> hi; 4 ■ 

i:5;.i ^' 

AX^C 
C H hi: C^ K E R I-: O R M E <l> Hi A O E 
QERROI-;: 
7 SYNTAX ERROR 

AKcc|;;2;;i 1 '^^-S 
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) s :i: 
ABC i:: 3:3 A 

n A r T H x s f- o :i: m t y c a h c o n t x m u b i::-: x ii-: c^ u t :i: o m 

■•>0i-ctl 

RESUME AT LINE' 4 

n I"- u M c T X o ii H f^ s H" :i: n :i; ii> i-i e x:i i-i: x e c^ u r x o tt 
flHEXT xs AN :i:mmex:i:i:ate mox:ie err or 
c f ■ A 
;|, 1 VALUE ERROR 
CtA 
A 
H CHECK OL.OBAI... VALUE OF QEPirROR 
OERHilOR 
11 S/ALLM:-: ERROPi; 
C:A 



The three lines of text in UERROR are exactly the same three lines APL 
displays on the terminal. 

UERROR can contain up to 384 characters. If the line containing the 
error is too long to fit in UERROR, APL truncates the line and prints 
the significant portion containing the error. The last character will 
contain -1\UAV. 

Note that if an error occurs during an i execute, then UERROR con- 
tains six lines of text. For example: 

X ' WW ' 
11 .t VALUE ERROR 
MW 
A 
25 EXECUTE EF!:ROR 
.1 ' WW • 
A 
OERROR 
11 X VALUE ERROR 
WW 
A 
25 EXECUTE ERROR 
j; ' WW ' 



For more information on UERROR, refer to Section 6.5. 
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4.2.10 UGAG - Preventing Interruptions 

The UGAG system variable allows you to prevent certain messages from 
appearing on your terminal. On both the TOPS-10 and TOPS-20 operating 
systems, users have the ability to send each other messages. On 
TOPS-10, a user can send a message with the SEND command; on TOPS-20, 
ci user can send a message by LINKing to you with the TALK command. 
You set UGAG to either 1 or 0. The default is installation-dependent. 

On TOPS-10, UGAG^l means "TTY NO GAG" - Accept Messages 
UGAG^O means "TTY GAG" - Refuse Messages 

On TOPS-20, UGAG^l means "RECEIVE LINKS" - Accept Messages 
UGAG<-0 means "REFUSE LINKS" - Refuse Messages 

On TOPS-10, if you return to monitor level, the DGAG setting will not 
inhibit messages. On TOPS-20, the UGAG setting remains in effect at 
monitor level. 



For example: 



fl TOPS.. .20 

OGAG 
)MON 

mdn:i:tqr * 
Qi term 

TERM:i;NAi... LA 36 

TERMINAL SPEED 300 

RECEI^^E LINKS 

REE USE ADV:i:CE 

R E c E I y i;;: s y s j e m ■•■ m i;- s s a g e s 
term;i;nal no "^c 

{»cant 
A I"' 1... i:; I"- ♦ 

OGAG 

:l. 

i:;|GAGf.o 

) M O N 

MaK':i:roR ♦ 
(■^:i, term 

TERMINAL LA 36 

TERMINAL SPEED 300 

REEUSE LINKS 

REFUSE ADM ICE 

I-;; E c i;- :i: t,-" i;:: s y s r i;;: m ■■ ■■ m i;;: s s a c^ Er c 



htops....:i.o 

OGAG 





) CONT HOLD 

IS? 46? 24 II JUI.......79 2 BI...KS 

"f r- v 4 4 ) 15 tA6t2A 1 1 ■ •■ -J *■■> ••■• -• 7 9 

c o n H III: c 7- (•■ r.> * \. 1 7 '■■■ f- *■■> ^ :i: m i;;: q toot 

2 s T A T 1;;: M I;-: a T s <•' '"' '==• <"•'■ ^-^ '^" •'• o ti b 

l< I i... O ... C O l=i: 1:1; .... S B C S ■] 

EXIT' 



4-li 



APL SYSTEM COMMUNICATION 



*I TTY 

RZ363A KL #1026/:!. 042 :I.5J46?3S TTY44 svjstem 1026/1042 
Connected to Node KL:I.026 (26) Line # 44 
Job 6:1. User masellAj/S ♦ i:: 2 7 -^ 26:1.7:1 
DSKC:J Kl...:l.026 Swstein disk DSKC 

ERlCt T0PS-:l.0 Benchmark SIR with 7»00 monitor 

DSKB? KL:l.026 S ostein disk DSKB 

NOLC NOTABS NOFORM ECHO CRI...F WIDTH J 72 GAG NOD IS PI... A 
F.i:i...l... M. NOT A 

*RU APi...sri::6:i. :i. i'S:i.72::i 

terminal « tifi, 

ft I"- 1... ••.• :|. D B Q s r i:> r b m •••■ % q cm I"- i... s f 2 ( 4 :t. 2 ) 

r- r- r .4 4 > 1 5 ♦ .4 7 » 8 w iii: x:i ii iii: <•> x:i r-y, r 1 i ... j u 1... .... 7 9 m f-^ s ii." 1... 1... a y s ^ |;; 2 7 y 2 6 1 7 ; 

<i A V 1;;: D I >■;; t .4 <fj ♦ 2 4 :l. :l. •• '••' '••• ••■■ 7 9 2 '< 

[JGAG 



i;;|GrtGM 

) co?rr Hoi....i:> 

:l. 5 J 47 J 33 :l. :l. JU1......79 2 ^^■■■^^^ 

•T- r- r- 4 4 ) :|. S ? 4 7 J 3 4 :l :l. ••■• >•' ^-^ i- ■••• 7 9 

CONNECT Hi: It:- o;00?25 ^^■^■> t:i:me 0?00?00 

2 STATEMENTS J, OPEPi: AT X ONS 

i<:i:i,..o-coRE-SECs 9 

ex:i:t 

O: TTY 

RZ363A Kl... ti 026/. 1.042 :l. 5 J 47 J 42 TTY44 swstein :l 026/. 1042 
Connected to Node KL 1026 (26) Line # 44 
Job 61 User MASELLAvS* i;:27y2617:J 
DSKC? KL1026 Swstem disk DSKC 

eric: tops- 10 Benchmark STR with 7^00 monitor 
DSKB J KL1026 System disk DSKB 

NOLC NOTABS NOFORM ECHO CRLF WIDTH: 72 NOG AG NODISPLA 
FILL J 1 NOT APE TYPE^c 



You can localize UGAG in a user-defined function. UGAG cannot be 
saved with your workspace, however, its setting remains unchanged 
during a )LOAD or a ) CLEAR operation. 



4.2.11 UIO - Index Origin 

The UIO (index origin) system variable changes the setting of the 
index origin. This setting determines whether the values of a vector 
or array are indexed beginning with position or 1 . The default is 
1. 

The index origin is important in array operations and in conjunction 
with roll and deal (Sections 3.2.4 and 3.3.3). The value is saved 
when the active workspace is saved and is only meaningful if it is 
or 1. This system variable is equivalent to the ) ORIGIN command. 
Section 5.5.4. UIO is used with the following operations: \A , ?A, 
A?B, All, A\B. 
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For example: 




O^tOfl 




13 


1 2 


3 

i:;i<-A<-2 4fi6 


1 


2 3 4 


5 


6 12 




»/i::23'^ 


10 : 


L4 

»/i;:i;i'^ 


6 e 


4 6 

*/Lo:i" 


8 


XNtilrJK ERROR 




•f/L:o:i« 




A 




I:J3:c)<0 




13 


1 


2 




»/i::2::iA 


8 


i:ndex error 




♦•/i;:2:ja 




A 




f/i;:i:iA 


10 


14 

•t/i;:o:]« 


6 


4 6 



4,. 2.12 ULC - Reporting on Executing Functions 

The ULC (line counter) system variable is used to obtain a partial 
report on functions that are currently being executed. It is stored 
as a vector of the line numbers contained in the state indicator, 
arranged in order of the most recently suspended function first. The 
default value for ULC is 0. 

The ULC system variable is particularly useful in branch statements 
(Section 6.4.1). You can specify that execution is to resume 
immediately following the line number at which function execution was 
most recently suspended with ULC. 

For example : 

v;>NEW 

[: 1 1 ■> 1 

ii I:-; w 

1 B {-^ r r E N r x a m s x g n <;m i... iii: d 
^'Kwn;] ••>1 



GI...C 
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4.2.13 ULX - Latent Expression 

The ULX (latent expression) system variable takes the expression you 
assigned to it before you saved the workspace and executes that 
expression automatically when the workspace is loaded. The value you 
assign to ULX must be a character string. APL processes the express- 
ion as if you had specified lULX , the execute function. Any error 
messages you receive from the use of ULX are produced by the execute 
function (Section 3.4.3). The default value for ULX is '*. 

The ULX system variable is often used to display a message when the 
workspace in which it is defined is loaded. 

For example: 

QL-Mf ' ' ' HOTH Nl-.W U \ HE.f- l'' 1 1 >rE)k .I.N t)l" I- RAT i < if j ' ' 



This system variable is also useful in restarting a suspended 
function. For example: 



It is also useful in invoking a particular user-defined function 
(Chapter 6) when you load the workspace. For example: 



Upon loading a workspace, APL executes ULX when the )SI stack is 
either empty or has a suspended function on top. If a function 
executes a )SAVE command, the function will continue when the work- 
space is reloaded, but the ULX system variable will not be executed 
because the function on top of the ^SI stack is not suspended. 



4.2.14 WUM - Digits 

The UNUM system variable is a subset of the UAV system variable 
(Section 4.2.6). UNUM contains a vector of the ten digits, 0, 1, 2, 
3, 4, 5, 6, 7, 8, 9. 

For example : 

IJNUM 

0123456789 

OAV i|j?n.jM 
305 306 307 308 309 3:1.0 3:l.:l. 3:1.2 3:1.3 3:1.4 
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4.2.15 DPP - Output Precision 

The DPP (print precision) system variable determines the precision of 
noninteger output by allowing you to set the number of significant 
digits to be displayed. Legal values for DPP are integers 1 through 
18. The default is 10. The DPP system variable does not affect the 
precision of internal calculations or the display of numeric constants, 

For example: 

123456789 ♦ J.2345A789 
:l 23456789*1 

CF^P^f-5 

123456789*123456789 
l*2346is"8 

123456789*123456789 
123456789*123457 



APL rounds off a number if it contains more digits that the setting. 
The precision you specify is saved when the active workspace is saved 
DPP is equivalent to the )DIGITS command (Section 5.5.1). 

The DPP system variable is also relevant to the conversion of numbers 
to characters with the monadic format function (t), Section 3.4.6. 



4 .2.16 DPW - Determining the Width of the Output Line 

The UPW (page width) system variable sets the maximum number of 
characters that can appear on a terminal output line, before a 
carriage return/line feed is performed. Legal values for UPW are 
integers 30 through 390. The default is 120. UPW has no effect on 
the display of messages or the length of input lines. 

For example: 

i;;i''w<-30 



Qi-m- < th:i:s 

TH.tS :i:i:> rt TEST Of 
TH VARIABI...I; 



i: s Pt T B s r D !"• T i-i i:i: ("■ f^ c^ in: w :i: t> r h v f^ r :i: n b i... i-;: 
n-iiii: PAGiii: w:i:d 



The width is saved along with the active workspace. DPIV is equivalent 
to the ) WIDTH command (Section 5.5.6). 
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4.2.17 DEL - Setting a Random Link 

The URL (random link) system variable sets the seed of the pseudo- 
random-number generator in APL. This generator is used with the roll 
and. deal functions (Sections 3.2.4 and 3.3.3). The range of meaning- 
ful values you can specify is -1+2*1 through -1+2*3 5. The default 
value is 0. 

Every time you specify either a roll or deal operation, you change the 
value of the random link. 

For example : 



1 3 S 2 4 

'==:'-• 
30388006192 

5?5 

14 5 3 2 
nP:i.- 

9311234783 



The value of URL is saved when you save the active workspace. 



4.2.18 USF - Setting the Evaluated Input Prompt 

The USF (signal for evaluated input) system variable changes the 
standard signal message used as the prompt in accepting evaluated 
input. You can use any printing character (s) as the prompt for 
evaluated output. The default is: 

D: carriage return/line feed 6 spaces 

For example : 

A*- 3 +0 + 5 

fit 
13 

KM-0 

' :i:nput • 

B 
.TNPUT 

OSI"<!- ' WHAT IS YOUR NAME'!> ' 

WHAT IS rOUFi: NAME'P 'SARAH' 

C 
SARAH 



Note that you must enclose the character input within single quotation 
marks in evaluated input. 
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4.2.19 UTIMELIMIT - Setting a Time Limit 

The UTIMELIMIT system variable sets a limit to the amount of time you 
have to respond to a quote-quad input request (H) or a quad-del input 
request (0) . The range of meaningful values you can specify is -1 to 
262143 milliseconds. 

Example: 

i:;i -f ■ ;i: M E I... :i: M :i: T< ■ '5 

Afl'J 
YOU HAVE EXVE SECOWDS 

YOU I -I AVI-:: f;i:ve seconds 

YOU HAVE f:i:ve se cohds 

X J. VAI...UE ERROR 
CONDS 

A 

flRAN our OF TIME 

YOU HAVE f:i;ve se 



If you exceed the time limit, APL accepts only the data you typed 
before you ran out of time. Any input accepted ends with a carriage 
return/line feed. 

Note that by specifying a negative argument (-1) to UTIMELIMIT , you 
can set APL to accept type-ahead input. This feature can be useful 
if you are accepting input from a pseudo-terminal (PTY) . 

To find out whether you or another user ran out of time, use the 
UTIMEOUT system variable (Section 4.2.20). 



4.2.20 UTIMEOUT - Reporting on Time Limit 

The UTIMEOUT system variable reports whether a user ran out of time 
during a quote-quad input request (Q) or a quad-del input request 
(S) with a UTIMELIMIT set. UTIMEOUT is set to either 1 or : a 1 
means that the user ran out of time, a means the user did not run 
out of time. 
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For example : 



0t:i:mi-::i...:i:m:i:t<s..5000 

YOU HAve: i":i:vKi: seconds 
[■|t:i:mi:::out 



f^x:i:ni:" hot run out of tikme 

you have h":i:ve seconds 
j :l, value error 
seconds 

A 

|;;|t:i:meout 

:l. 

nRAN out of t.tme 

The value of UTIMEOUT remains constant until you type one of the 
following: 

1. Quote-quad input from the terminal (E) . 

2. Quad-del input from the terminal (0). 

3. Input from a pseudo-terminal (PTY) . 

4.2.21 UTRAP - Trapping Errors 

The uTiT.42' system variable takes an expression you assign to it and 
executes that expression when an error occurs only during function 
execution. The value you assign UTRAV can be any valid APL expression 
in the form of a character string. The default value is null, or lO. 

You can set UTRAF as a global variable or localize it in a function. 
If an error occurs, APL searches for the most local UTRAP . If UTRAP 
is set to anything other than null, APL executes UTRAP in the environ- 
ment of the function where the error occurred. 
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For example : 



[■■3:1 ^■''■■'^* 
r.4.:i 

i::7.i 
i:.a:i 






■■■i"iv,-nK ii ' I '1.." 



r-.(:vpVi:Oi;: 



)«:>:i. 



■^->^nnt nrfiAP set: 
. illustrates what happens without 
The following exawle -l^"^" 



> «;: X 



{■■'■) 1 ift.O 



G 



A 



orute function you can 

.u the e.o. -r or^f^saa^^^^^^^^^^ ^eT.U^-- 

^^^r-t. ict, onl. the 

. halts .ue to settm. the trace and 
1 Function halts ^-vcinq 

and J^n to n or !J inP"^ °' '^^^^"^ 

, input halts fro.tvpxn..(-0-' 

-. to D input 



to D input 

^ or T execuce 
3. Errors m c or t 
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Because you can execute a function call from a UTRAP , you may want to 
localize [jTRAP to avoid unwanted loops. 

For information on error handling, refer to Section 6.5. 



4.2.2 2 DTS - Reporting Current Time and Date 

The UTS (time stamp) system variable obtains the current time and date 
and stores it as a 7-element vector in base 10 format. This vector is 
known as a timestamp and contains the following elements: 

current year, month, day, hour, minute, second, millisecond 

For example: 

i::iTs 

1979 7 2 :l.3 44 47 70 



4.2.2 3 UTT - Reporting Terminal Type 

The UTT (terminal type) system variable contains a value that relates 
to the type of terminal being used for the current APL session. When 
you run APL, you specify the terminal type in response to 

term:i:hai... , , 



APL stores this information according to the following table 



Table 4-4 
UTT Terminal Types 



Value 


Meaning 





TTY-type terminal 


1 


TTYCOM terminal 


2 


LA36 or Tektronix 4013, 4015 


3 


APL keyboard- or typewriter-paired 




ASCII/APL terminal 


4 


APL bit-paired ASCII/APL 


5 


APL ONTEL 


6-9 


Reserved 


10 


2741 Selectric-Type 



For example: 



r:iTT 
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4.2.24 UUL - Reporting the Job Number 

The UUL (user load) system variable contains the system job number 
associated with the current APL session. The value is stored in base 
10 format. 

For example : 

oui... 
18 



4.2.25 UWA - Reporting the Available Work Area 

The UWA (work area) system variable contains the amount of available 
storage space in the active workspace. This value allows you to 
determine the maximum amount to which your workspace can increase. 

The size is given in bytes, not words. APL obtains the value by 
subtracting the current data-segment size from the maximum data- 
segment size. 

For example : 

i;;|WA 
73232 



4.3 SYSTEM FUNCTIONS 



The system functions described in the following sections allow you to 
perform such operations: 

1. Expressing the canonical representation of a function and 
storing the function definition as data 

2. Expunging a named object 

3. Constructing a name list of labels, variables, or functions 
and returning the classification of a named object 

4. Delaying execution of a function for a specified period of 
time 



There are certain system functions that are relevant only in conjunc- 
tion with the file system, for example, UAFPEND and CASS. These 
systems functions are described in Chapter 7 . 

System functions are an integral part of the APL language and can be 
used freely in all APL function definitions. The names of the 13 
system functions described in this section all begin with a quad (D) 
character and are reserved words. Like system variables, system 
functions cannot be copied, erased, or collected in a group. 
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You access a system function by simply stating its name with 
arguments, as you would access a primitive or user-defined function, 

The system functions described in this chapter are: 



UBREAK 


Section 4.3.1 


ncR 


Section' 4.3.2 


DDL 


Section 4.3.3 


UEX 


section 4.3.4 


UFI 


Section 4.3.5 


OFX 


Section 4.3.6 


UNC 


Section 4.3.7 


UNL 


Section 4.3.8 


UQCO 


Section 4.3.9 


UQLD 


Section 4.3.9 


UQPC 


Section 4.3.9 


QSIGMAL 


Section 4.3il0 


UVI 


Section 4.3.11 



4.3.1 UBREAK - Suspending Execution 
Format 

UBREAK arg 
where 

arg is any APL object. 

The UBREAK system function suspends execution of the function in which 
it is contained and returns you to immediate mode. 

UBREAK is a monadic system function. It takes any APL object as an 
argument and prints that argument before breaking to the terminal. 

For example: 



[; 1 :;i 


> F :i; r: 


:ST 1 


1... :i:ni:i: ' 


1:2:] 


OK RE 


AK 


' BREA 


1:3:1 


« RES 


.UME 


AT 1... 


1:4.] 


FUNC 






f:i;h;:st 


1... :t:HE 






BRBf^K 


AT 1... 
) S X 


:i:nii:: 


'? 


FutiC\"';, 


n f. 








■■iU\...v. 


M. 




F::ili:sUMI:i 


'■:. AT 


1... :i:k'i 


(••: 3 



To return to function execution after a break, you can either go to a 
specific line number (->-3) or use the system variable ULC . Specifying 
ULC would return you to the line where the UBREAK executes. To resume 
at the line after the breakpoint, specify ULC+1. 

Note that UBREAK is illegal from immediate mode and e execute. 

For more information on the use of UBREAK, refer to Section 6.5. 
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4 .3.2 DCE - Obtaining a Canonical Representation 

Format 

DCi? arg 

where 

arg can be a function name enclosed in single quotation marks or 
a variable name whose value is the name of the function. The 
rank of the arg (for example .4) cannot be greater than i, l>ppA. 

The function you specify must be a defined and unlocked function. 

The UCB (canonical representation) system function provides a canonical 
representation of a defined function. A canonical representation is a 
character matrix with rows consisting of the original lines of the 
function definition reformatted to be of equal length. The V symbols, 
line numbers, and brackets are removed from the definition. Lines 
that contain labels are shifted to the right so all text begins at the 
same character position. Lines are then right-padded with blanks to 
make all lines equal to the longest line of the function. This for- 
matting allows you to treat the function as data. 

The following example illustrates the original function to be refer- 
enced by UCH and the matrix or canonical representation that results 
from the operation of the system function. 

For example : 

V M !■■ n n ? c * • N *i> ij » ^j M I:-: a h ;-c 

i:. 1 J n 1:H,.l M V 1:=: C^ T O R X 

121 SUMX <■■♦•/}■; 

r 3 .1 M K:: A H X t- S U M >i ■■■:■ tt *S> U K' .J 

i:; ■^ "I V 

I J 'A.' ||Ci=i: ' MKIAN ' 
MP:rtNX<.N<.;UH,J ME' AH :< 
HSUM VI::fTOi;- M 

M ii=: A H >: i- S U M X v M i:> U i.< J 



A n.i 



A. 9 



/*A 



"if.J ,^. ^ 9 5 A 2 1 7 A 

10 MII.'A?' X 



If the argument to DCi? does not represent the name of a defined and 
unlocked function, the resulting matrix is a null matrix, by O. APL 
returns a 9 RANK ERROR if the function name is not a vector or a 
scalar, and a i& DOMAIN ERROR if the argument is not a character array 
or if the name is not enclosed in quotation marks. 

The UFX system function {Section 4.3,6) reverses the effects of DCi?, 
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4.3.3 DDL - Delaying the Execution of a Function 

Format 

UDL arg 

where 

arg is the number of seconds you want to delay execution. The 
argument must be a scalar or vector with a single numerical value 
{l>pp ARG) or APL returns a 9 RANK ERROR or a 15 DOMAIN ERROR. 
There is no limit to the value of the argument. 

Although UDL specifies the desired duration of the delay of the 
function, the actual delay can be somewhat different. Other demands 
on the APL system at the time that the UDL is issued can affect the 
accuracy of the delay. In addition, you can use a single attention 
signal, CTRL/C, at any time to abort the delay and cause an interrupt 
in the function in which the UDL appears. 

For example : 

DEi...-s-[:|x:>i... 2 
Di-;:!... 



DEL is a scalar value equal to the actual delay incurred as a result 
of the 2-second UDL specification. 

The UDL function uses a negligible amount of computer time; you can 
issue it freely in situations where tests are required at periodic 
intervals to determine whether or not an event has occurred as 
expected. 

This is helpful in simplifying interuser and interprogram communica- 
tion of various kinds. Another way to wait specifically for input is 
to use UTIMELIMIT , Section 4.2.19. 



4.3.4 UEX - Erasing a Named Object 

Format 

UEX arg 

where 

arg is a function name enclosed in single quotation marks or a 
variable name whose value is a matrix of function names. 
Therefore, the argument can have a rank of 2 or less (2>ppi4i?G). 

The UEX (expunge) system function erases a variable or function name 
so that you can reuse it without confusion. UEX operates on global or 
dominant local variables. You cannot erase a named object that refers 
to a label, a group, a suspended or pendent function, or a system 
variable. 
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When you erase a name (or names) HEX returns a 1 or a depending upon 
whether the name was successfully erased. A 1 signifies that the name 
was erased; a signifies that the name cannot be erased. You also re- 
ceive a if the name is not a legal APL variable name. 

APL returns a 9 RANK ERROR if the argument has a rank higher than 2 , 
and returns a 15 DOMAIN ERROR is the argument is not a character string, 

For example: 

)FNS 
A I? CD GROW TEST 



A f ■ 3 4 f ' c^ B c Li r e: s r g r o w ' 

TEST 
(5 ROW 

OEX A 

1 1 :l. 

)FNS 

(APL outputs at blank lines) 
4.3.5 UFI - Converting Characters to Numerics 
Format 

UFI arg 
where 

arg is a character scalar, vector, or one-element array. 

The UFI system function takes a character argument and converts it 
into a numeric, placing zeros in each position that does not corres- 
pond to a valid number. Note that a minus sign preceding a number is 
not part of the number but is rather an operation to be performed on 
the number. However, in the expression ~5, the negative sign is a 
valid part of the number in APL. 

For example : 

v:;c:<-avk;;rage; 
LIU ■>"<■ y l!l? n< ' k:ntih:r a l. :i:st of numbers' 

1:2:1 ^<-(i:iv:i: ■^)/nF-r. z 

1:43 V 

AVEPrAGE 

A l._;i:ST OF NUMBERS 

1 ^*5 « «-2 ■■'♦5 6. * 



In the previous example, 

UVI is 11011110 
UFI is 13. 5002 .560 
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4.3.6 UFX - Establishing a Function 

Format 

UFX arg 

where 

arg is the name of the character matrix that contains a canonical 
representation of a function. The rank of the argument must 
equal 2, 2=ppABG. 

The UFX system function reverses the operation of the UCR system func- 
tion (Section 4.3.2). If a function already exists in your workspace 
with the same name, LiF.Y replaces it. 

For example: 

^^ I" :.'! V 6 :i «■• ' X ' 

MEAH 

v;'MI::.AHi::|::|.|V 

II' .1. J flSUM \'I:"C Toi-;: y. 

L?.".\ SUM J;*- X /:■■'■ 

!_■ ;j; ';i m ip: n r >. x f- <.; i..i m ;■; ■■ ■ i> s '. i x:< ..i 

^^ ;^ V S 4 2 :l. 7 4 

;) Mir.Af! y 

1.4 5:1/;. 2 



The rules for local names apply to the names of any functions estab- 
lished by the UFX function. 

UFX will not establish a function if the name of the function to be 
established is the same as that of an existing label, variable, or 
group, or an existing function that is currently pendent or suspended. 
A pendent function is usually one that is awaiting return from another 
function. The UFX executes properly if the matrix referenced by UFX 
is identical to a canonical representation, except for the addition of 
blank characters in rows other than those consisting only of blanks. 

If UFX cannot establish a function, APL returns a scalar index 
representing the row in the matrix where the error occurred. No 
change is made to any function or matrix in your workspace. 

APL returns a 9 RANri ERROR if the argument is not a matrix, and a 1.5 
DOMAIN ERROR if the argument is not a character array. If UFX is 
successful, its value is the name of the function defined. 
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4.3.7 UNC - Returning a Name Classification 



Format 



UNC arg 



where 

arg is a character matrix of names or a vector or scalar con- 
sisting of one name. The rank of the argument is 2>pp ARG. 

The UNO (name classification) system function returns the classifi- 
cation of a name or group of names. If the argument is a matrix, 
UNO returns the class of the name represented by each row in the 
matrix. If the argument is a vector or scalar, UNO returns the class 
of a single name. UNO returns a numeric value representing each name 
class. Table 4-5 lists these values. 



Table 4-5 
UNC Classes 



Value 


Meaning 





Name available for any use 


1 


Label name 


2 


Variable name 


3 


Function name 


4 


Not available for use as a name 



A value of 4 implies that the argument is not a valid name or that it 
is currently in use as a group name (Section 5.4.4). 



For example: 



QtiC 
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.3.8 UNL - Constructing a List of Labels, Variables, or Functions 



Format 

JaJa^L n 

where 

a is a scalar or vector of alphabetic characters. The letters 
must be supplied in alphabetic order. This parameter is 
optional. (Do not type the square brackets.) 

n is one or more integer scalars or a vector from the follow- 
ing list: 

Values Meaning 

1 Labels 

2 Variables 

3 Functions 

The UNL (name list) system function can be either monadic or dyadic 
depending on whether you supply the left argument. In both forms, the 
function constructs a list of named objects residing in the active 
workspace. The "n" parameter identifies the type of named objects to 
be included in the list. 

For example: 



causes the names of all labels and variables in the workspace to be 
included in the name list X in alphabetic order. Each row of the 
matrix will contain the name of one label or variable. The number of 
columns is determined by the length of the longest name. UNL fills 
the shorter names with blanks to the length of the longest name. 

The dyadic form of UNL allows you to restrict the name list to names 
beginning with specified characters by including an "a", left argu- 
ment, in the expression. For example: 

ii I... :i; s T f . ' f^ B c x;i ki: f • |;| n i... 3 
Ni... :i;<:rr 

AVERttGE 

Cftfi: 

FUWC 



causes a name list to be constructed of function names whose initial 
letters are A through F; the list is arranged in alphabetic order. 

The UNL system function is useful for a variety of purposes. Some of 
these are described below: 

1. UNL can interact with Z\CH (Section 4.3.2) in creating func- 
tions that can automatically display the definitions of all 
or a subset of functions in the workspace. You can also use 
it to analyze interactions between variables and functions. 
(Remember to remove the blanks on the right, if any exist.) 
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2. In conjunction with UEX (Section 4.3.4), the UNL function can 
cause all of the named objects in a certain category to be 
erased dynamically. It also helps the design of a function 
that can be used to clear a workspace of all but a preselected 
collection of named objects. 

3. In its dyadic form, UNL can guide you in choosing names while 
developing or interacting with a workspace. 

The following example illustrates the construction of a matrix con- 
taining the names of variables in the active workspace that begin with 
the letter V. 

HI... ISTf. ' V ' pNL. 2 

HLIST 
VAH::;|. 
Vftl-i:2 
VAP:203 
VAF.:99 
VBMAX 



4.3.9 UQLD, DQCO, UQPC - Loading and Copying a Workspace 

Format 

UQLD arg 
UQCO arg 
UQPC arg 

where 

arg in each case is a character vector (enclosed in single 
quotation marks) representing the workspace name, an optional 
password and an optional list. 

The password is the password associated with the owner of the 
workspace. The password is necessary only if you are not 
privileged to access the particular workspace. (Do not type the 
square brackets.) 

The list is an optional parameter used to identify specific 
objects to be copied. If you omit this parameter, all functions, 
variables, and groups in the workspace are copied. (Do not type 
the square brackets.) 

The UQLD, UQCO, and UQPC system functions perform the same operations 
as the )LOAD, )COPY, and )PCOPI commands described in Chapter 5. UQLD 
loads a workspace, UQCO copies a workspace, and UQPC copies a work- 
space with certain protection considerations. 

Unlike the system commands, the system functions do not return messages 
to verify a successful load or copy. The system functions, however, 
return the messages OBJECTS NOT FOUND and NOT COPIED: when applicable. 
These are not inhibited. 
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Also, APL does not output a blank line to indicate that no value was 
returned. Therefore, you can use one of these system functions alone 
or as a function line without blank lines appearing on your terminal. 

If the, tJLX has a value; in the workspace, it: also executes with the 
QQLD. ■ 

The UQPC system function does not cause APL to return the names of 
objects that were not copied. 

If an error occurs during the execution of any of these three system 
functions, APL prints an error message. Therefore, you can trap 
errors as usual with the use of the execute function (Section 3.4.3). 

For example : 

)I...OAr' T 

SAVK:it:. 13 J 53: 13 11 nji.......79 ^p 

A 
1 

) CI...EAR 
CLEAR W<:> 

[■|ai...x:i ' T ' 

) W S X II' 

f <oo7> i:;4y204:.i 

A 
1 

) CLEAR- 
CLEAR WS 

)COPr T A B 

SAVED 13 J 53 J :l. 3 11 JUL... 79 6'==- 

A 

:l. 

B 

2 

c 

11 VALin-.-: ERROR 
C 
A 
) CLEAR 
CLEAR W*:> 

[jaco ' T ' 

1 

B 

';> 

3 

) clk::ar 

CLEAR WS 

0«CO ' T A B ' 

1 

B 



11 VALUE ERROFi: 
C 
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)CLKi:AI=i: 

CI..RLAK WS 

)COPY T A x:' 

s A V fj: x;. :|. 3 * s 3 ♦ ;|. 3 1 1 > *..' i- •• 7 9 6 ••'■ 

OBJECTS NOT FOUNX." J t> 

A 

1 

](■:< 

tj. VAI,..UI:;: ERROFt 

x;< 

A 
) CI... EAR 

CLEAFi: WS 

[■|aco ' T A x:> ' 

OBJECTS NOT FOUNXIi ♦ Xi' 

) CLEAFi: 
CL.EAR WS 



)F:CCM"Y t 

sAVEx:. j.3:53t:l.3 :l. :l. H.J1.......79 ^i 

NOT cop:i:ex:>j a 

Pi 

20 



3 

) CI...EAF;: 
CLEAF-i: WS 

Ai!-20 
napc ' T ' 

NOT COF'lRnx:i J A 

A 

20 

B 

2 

c 

3 

)CL.EAFi: 

CLEAR WS 

Z4-0aCO ' T A D ' 

OB^iB C T S M O T F" O U i( V * 
f>'Z 



)CLE::AR 

CLEAR WS 

Zf.fJQRC ' T A B ' 

OBJEHCTS NOT F'OUNB} 
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4.3.10 USIGNAL - Signalling Errors 

The USIGNAL system function allows you to pass an error up the stack 
O-ST) one level to the caller of the function in error. The syntax of 
USIGNAL also allows you to make up your own messages. The syntax has 
the following format: 

error message USIGNAL error number 

where 

error message is an optional character string. 

error number is a scalar or a single-element array of any rank. 

The value you supply as the error number can be any APL error number 
as listed in Appendix A or a number from 500 to 999 inclusive. The 
message sent by U3IGNAL is stored in "OiEEROR. The error number you 
supply USIGNAL becomes the number in the first line of UERROR. If 
error number is the number of an APL error, then the message stored in 
UERROU is the error message that coincides with that number, regard- 
less of the left argument. If you supply your own number, you can 
either make up a message or leave the left argument blank, in which 
case you would receive the default message: 

ERROR SIGNALED BY FUNCTION 

For example : 

nFUNCT:i:aw f mas os.i:(jNai... 

CI 3 ••><'^>0)/3 

|- 2 :] • w :j: u l w o i a c g k: f r ?•« e" e a t x v e j« u m b e n-. s • p is :i: ci h f-^ i.. «j q % 

r 3 '3 ' ^ *•' '■* *- "'' •'• ^ *'* ^" '•> *' "f ' '^- '■* *"* '•- "* '•' <^ '^''' ^^-^^ '• •• '^' ' 

flFUHCrXOH H CAL.I..S F 
K?H A 

mi '==■ « 
i:2:j ^ 

H 5 
F u ti a T :»: o h c o n r :r. tt u i-i: s w o r m a i... i... y 

Uli::fi:Fi:OR 

) <■; ;i; 

H -y 
50:1, w .i: I... I... NOT ACce.PT nkkcvA t;i:vit:: NUMKfj'KftiiJ 

Hi:.i.::i f a 

A 

OliiRROR 

'iO'i. w:i:i..i.. nor acceft f-n-iiGATiiA-'i;:: hum»j."-:r-s 

•■••j.;;i.::i >■■■ a 

A 

) - .c 

HL"i.;:i A 
Notice that the error is signaled at the level of the caller, //, not F, 
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It is illegal for you to execute UCHGNAL in immediate mode or with i 
execute or e execute. 

For more information on the use of USIGNAL refer to Section 6.5. 



4. 3.11 UVI - Validating Input 
Format 

UVI arg 
where 

arg is a character vector, scalar, or 1-element array. 

The UVI (validating input) system function is used in conjunction with 
the UFI system function (Section 4.3.5). While UFI converts a char- 
acter vector into a numeric vector, UVI returns a Boolean vector that 
contains a 1 in each position corresponding to a valid number that can 
be converted with UFI. It returns a for nonvalid numbers. 

For example : 

(">*■■' 1. '5 3 A •■■■5 3«* :l. *()"=;: :I.S M ■■"3' 

Ov:i: A 
:l. 1 1 1 1 

Of:i: a 
:L*5 3 "S l»000000000ii:"3.S ""3 

(i::iv:i: A)/Oi=^:i: f"^ 

:i.5 3 -s :i. ♦ooooooooo':^;:i.5 ■•■3 
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5.1 INTRODUCTION 

APL provides a wide variety of system commands to communicate with the 
APL system and to control the operating environment in which the APL 
session is conducted. System commands allow you to examine or change 
the state of the system. For example, they allow you to: 

1. Clear, save, or name the active workspace 

2 . Load or copy a workspace from a secondary storage device 

3. List workspace, variable, function, and group names 

4. Determine memory and workspace size, time and system 
resources used, and version and device information 

5. Display the status of functions and local variables in the 
workspace 

6. Set the index origin, the maximum number of significant 
digits, and the output line width 

System commands are not considered a part of the APL language itself, 
but can be viewed as an interface between you and the language inter- 
preter. System commands implemented for use with the APL file system 
are described in Chapter 7 . Appendix B provides a summary of the 
format of all system commands in alphabetic order. 

This chapter is structured in the following way. Section 5.1 provides 
an overview of the format for system commands, the two ways of using 
system commands (action and inquiry) , characteristics of workspaces, 
and APL libraries that allow you to share programs with other APL 
users. Sections 5.2 through 5.7 describe the system commands them- 
selves by category: 

Section Commands 

5.2 Basic Workspace-Control 

5 . 3 Extended Workspace-Control 

5.4 Workspace-Content 

5 . 5 Workspace-Environment 

5 . 6 APL Termination 

5.7 Miscellaneous 
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Section 5.8 discusses the special function of the execute function (e) 
in relation to system commands. 



5.1.1 System Command Format 

Unlike other APL statements, system commands begin with a right paren- 
thesis, as shown in the following format: 



) command-name |[ parameter-list || 



You can abbreviate the command-name to its shortest unique form, which 
usually requires no more than four characters. Some system commands 
require one or more parameters or arguments in the command string. If 
you include required or optional parameters, you must separate the 
individual elements of the command string with at least one space. 
(Do not type the square brackets.) 

The following examples illustrate the format of several system 
commands : 

) El X G ITS 5 
WAS 10 

) 1:1 1 G X 

5 

) 1.1 X C? I T 

'5 

)SAVin: MYWOPrK 

14:3B:1..1. 1:I.-JUI.......79 :i pgs 

)COn=Y WS 4 O- SESAME A i'f C VAK^f, N 

•Saved :|. 4 J 36: 45 :U. JUi... ..79 6i==- 

The first three examples invoke the same system command, ) DIGITS, 
since the first four letters of each of the command names are the 
same; note that extending a command name beyond its unique form (four 
letters) has no effect. In the fourth example, MYWORK serves as an 
additional argument to the )SAVE system command. The fifth example 
illustrates the inclusion of a series of parameters in the )COPY com- 
mand. Only WSH-0 is a required argument; the password and name list 
are optional (see Section 5.4.1). 



5,. 1.2 Action and Inquiry Commands 

You can use APL system commands for two distinct purposes: 

To obtain information - inquiry commands 

To change the state of a workspace or operating environment - 
action commands 

Action commands cause some change in the state of the APL system. 
Inquiry commands report on the state of the system but do not change 
this state in any way. 
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The )MON command is an example of an action command. To return to 
operating system command level, specify the following: 

) MOH 
MQHXTORJ 

Q? 



The )SI command, on the other hand, operates as an inquiry command, 
It reports the status of APL program execution. For example: 

)s:i: 
pk:i:mes|;:2;J * 



You can use many system commands as both action and inquiry commands. 
The distinction between action and inquiry is made by the inclusion of 
optional parameters. The ) ORIGIN command is an example of a command 
you can use in both ways. The ) ORIGIN command can either (1) change 
the index origin setting associated with an array specification 
(action) or (2) return the current setting of the index origin 
(inquiry) . 

The first example below shows the use of ) ORIGIN as an action command; 
this command sets the index origin to and also reports that the pre- 
vious setting was 1. The second example shows the use of ) ORIGIN as 
an inquiry command; this command reports that the current setting of 
the index origin is . 

)Or:i:Cv1n o 
WAS ;|. 

) ORXGXii 



5.1.3 Workspace Characteristics 

The APL system uses a buffer in your memory area to store functions, 
variables, and values, information on the status of functions, group 
descriptions, and any temporary results obtained while executing APL 
statements. When available in memory, this buffer area is known as 
the active workspace. 

You can enter system commands that cause this active workspace to be 
saved on a secondary-storage device; subsequently, you can load the 
saved workspace into the buffer area to function as the active work- 
space once again. The term "workspace" is used to refer to either the 
active workspace or a version of an active workspace now saved in 
secondary storage. 
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Many of the system commands described in this chapter aid in changing 
the status of a workspace. For instance, you can clear, save, load, 
name, lock, and delete a workspace. You can also copy functions, 
variables, and other eTements from a saved workspace into an active 
workspace and display their names. Workspace size, owner, and pass- 
word information can be reported. As an APL user, you have extensive 
control over the activity and characteristics of the workspace in 
your system. 



5.1.3.1 Workspace Names - Each APL workspace defined in your disk 
area has a unique name associated with it. In the command formats 
presented in this chapter, this name is represented by the parameter 
"wsname". The workspace name has five distinct parts: 

1 . Device name 

2 . Filename 

3. Extension or type 

4 . Protection code 

5. Directory 

Legal formats for these name components correspond closely to standard 
TOPS-10 naming conventions and are summarized on the following page. 
For TOPS-20 users not familiar with TOPS-10 conventions, refer to 
Appendix D. 



Part 



Format 



Device name 



Filename 



Extension or file type 



Protection code 



Maximum of six characters followed by a 
colon (for example, MTA:). 

Maximum of six characters (for example, 
TESTOl) . The rest will be ignored. 

Period or comma followed by a maximum of 
three characters (for example, .APL) . 
If you are using TTY mnemonics, you must 
use a comma (for example, ,APL) . 

Octal number in the range through 7 77, 
enclosed in angle brackets (for example, 
(<377>) . 



Directory 



Directory is a project-programmer num- 
ber, enclosed in square brackets (for 
example, [145,7231]). For TOPS-20 users 
with directory names, use the TRANSL 
command to find out the project- 
programmer number associated with a 
directory name. (Refer to Appendix D 
for more information on TRANSL.) 
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Characters you use in device names, filenames, extensions, and types 
can be ^4-2, A-Z,A>A, and 0-9. An example of a complete workspace 
name is: 

r> i:> i< ♦ M T- w o Hi: K » A f- 1... < % '5 7 > z 1 4 7 9 3 2 1. 6 ::i 



The system commands do not always require all five parts of the work- 
space name in the command format. When you omit parts of the name, 
the default values take over. These defaults are summarized in 
Table 5-1. 



Table 5-1 
Workspace Name Defaults 



Component 


Default 


Device name 


DSK: 


Filename 


Name of active workspace 


Extension or type 


.APL 


Protection code 


Installation-dependent 


Directory 


Your directory 



5.1.3.2 The CONTINUE Workspace - When you terminate an APL session 
with the )CONTINUE command (see Section 5.6.2) APL saves your work- 
space on disk and names it CONTIN .APL. The CONTINUE workspace is an 
image of the active workspace as it existed at the time of termination 
It has the workspace name: 

DSK: CONTIN. APL<std prot> [directory] 

where 

<std prot> is an installation-dependent standard protection code 

[directory] is your directory 

APL recognizes CONTIN as a special workspace. If a CONTINUE workspace 
exists in your disk area, APL loads it as your active workspace when 
you begin the APL session. This means that when you run APL instead 
of having a clear workspace, you will automatically have the workspace 
you saved with )CONTINUE. The CONTINUE workspace replaces any exist- 
ing one on disk. 

You can also backup your workspace periodically by setting the UAUS 
system variable to 1. Refer to Section 4.2.5 for more information on 

UAUS. 
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When you )CALL something, your active workspace is in CONTIN .APL and 
will start up at the line 1 plus the )CALL line. 



5 .1.3. 3 Workspace Passwords - In addition to the unique name, each 
APL workspace can also have a password associated with it. A password 
begins with a hyphen and can have up to eight more characters. The 
default is a hyphen (-) . This is considered a null password. For 
example : 

■SESAME 



Workspace passwords provide additional workspace protection. If you 
want to use a password-protected workspace, you must specify the 
password associated with that workspace before APL allows you to 
retrieve it from secondary storage. 



5.1.3.4 Groups - Various functions and variables in a workspace can 
sometimes be easier to work with when they are treated as elements in 
a single logical collection. This approach is aided by the "group" 
concept in APL, which allows you to treat functions and variables as 
logical entities. Several system commands are available that allow 
you to define a new group, list the members of a group, add members to 
or delete members from an existing group, erase or "undefine" a group. 
See Sections 5.4.4 through 5.4.6. 



5.1.3.5 The State Indicator - Every APL workspace contains a status 
vector known as the state indicator. This indicator stores informa- 
tion on the execution of functions within the workspace. You can 
obtain a report on the status of APL functions by issuing an )SI or 
)SIV system command (Sections 5.4.8 and 5.4.9). These commands list 
the contents of the state indicator, which identifies suspended and 
pendent functions. A suspended function is one that has stopped 
executing for some reason. A pendent function is one that contains a 
call to a function that has not completed. The pendent function is 
waiting for the called function to return. 

If the state indicator is "empty", no functions are currently suspended 
or pendent. The use of the state indicator in debugging and executing 
functions is described in Section 5.4.8. 
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5.1.4 APL Libraries 

A special library facility is available through the APL system that 
allows you to make your programs available to all APL users. You can 
save programs in workspaces on a library device and subsequently allow 
other users to retrieve them. All workspaces you store on a library 
device must be assigned a library-device name as the device name por- 
tion of the workspace name. A library-device name consists of the 
characters LIB, followed (without intervening blanks) by an integer in 
the range 1 through 999, followed by a colon. Some examples of pos- 
sible library-device names follow: 

I... :i: Mf I % 
I.. :i: x:< 4 4 '5 t 
i..;i:x:<00:l. J 



The third example, LIBOQl:, is equal to both LIBl: and LIBOl:. 

Workspaces specified with a library device do not have file extensions 
or file types associated with them. 



CAUTION 

LIB: activates a special password sys- 
tem, so if the library workspaces are 
removed to another area, you might need 
to rename them. 



5.2 BASIC WORKSPACE-CONTROL COMMANDS 

This section describes the basic workspace-control commands. These 
commands allow you to manipulate APL workspaces in a variety of ways. 
You can: 

1. Clear or name the active workspace 

2 . Delete workspaces when no longer needed 

3. List the names of workspaces in your area or in a library 

4. Specify, change, or return a password for a workspace 

5. Save the active workspace on a secondary storage device and 
retrieve it when required 
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5.2.1 ) CLEAR - Clearing the Active Workspace 
Command 

) CLEAR 

Example 

) CL..t:;AF:: 
CL.KKAR WS 



The ) CLEAR system command closes all open files and clears the active 
workspace by replacing it with a special workspace known as the clear 
workspace. ) CLEAR resets all the workspace constants to their defaults, 
APL also gives you a clear workspace when you begin a work session un- 
less you have the CONTINUE workspace (CONTIN .APL) in your disk area. 
The clear workspace contains the default values for all workspace 
related system functions: 

1. Contains no functions, groups, or variables. 

2. Has an index origin of 1 (Did). 

3. Has an output line length determined by the operating system 
width specification. You can change the output width with 
UPW. See Section 4.2.16. 

4. Displays numbers with 10 significant digits. This output 
precision can be changed with DPP, See Section 4.2.15. 

5. Has a clear symbol table and state indicator. 

6. Has the name CLEAR WS 

Cannot be saved without being given a name with either )WSID, 
or )SAVE. 

1. Has the null password hyphen (-). 

8. Requests quad input with the message D: followed by a 
carriage return/line feed and six blanks. (D-SF) 

APL uses a symbol table to record function, variable, and group names 
and constants. The size of this symbol table expands as new names are 
specified and is limited only by the size of the workspace. 
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5.2.2 )DROP - Deleting Stored Workspaces or Files 

Command 

)DROP wsname [[ switch-list]] 

Examples 

)x:iROF- :i;nt\b20 

9 n. 5 J 30 6 M.n.„....79 

)|...:i:b tb:si\a 

THST ^ ab:i: 
r E s r 

TEST »B20 
TEST ^MAC 

) xiiROF th;:st ^ a 

DROPPED ♦ 

TEST<, AB.i; 
TEST 

TEST, ©20 
TEST , MAC 

9tl6tlA 6--'i..H...-..79 

The )DROP system command is an action command that deletes stored 
workspaces or files. )DROP can delete any system file for which you 
have the necessary protection privileges. You can erase one, several, 
or all of the files on a directory device. To delete a single work- 
space or file, specify the. name as the parameter. As described in 
the )LIB command. Section 5.2.3, you can use an asterisk as a wildcard 
designator. If you use the asterisk, APL lists the deleted files. In 
both cases, APL displays the time and date of the )DROP request. 

You can also include a switch-list in the )DROP command string. These 
switches are the same as the ones listed in Table 5-2. If you include 
a switch, )DROP displays the information applicable to the file just 
prior to its deletion. For example: 

)DRDP WS9 /B 
XiiROPPIiKD I 

PILE Bl... KS 

WS9 :|. 

:l. 
9 I ;| 7 J 2 3 6 ■•■• ■••■' ^••' '••• ■■ ■ 7 9 



The example above displays the number of blocks freed by deleting the 
workspace named WS9. 

On TOPS-2 0, the file is deleted but not expunged. 
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5.2.3 )LIB - Listing Workspace Names 

Command 

)LIB Hwsnamej|ljswitch-list|j 

Examples 

) L.. .i; B 

ALPHA 

<:.M-IAR 

GEORGlii: 

Hi-RIME 

)SAVE' WS40 

14:56:23 11 n.n......79 i i=os 

) L. :i: B 
nsK ♦ 

AI...PHA 
CHAR 

georgk: 

PR I ME- 
WS 40 

)SAve: ws4(),VAFi: 

14:S7:32 11 JIH.....79 ;|. PGS 

)i...:i:b ws40,ft 
x:>SK ♦ 
WS40 

WS40, VAR 



) I... .1: B * , ft 
nsK ♦ 

AI..F-HA 
CHAPi: 
GEORGE 
L.OG:i:N»CMt> 

l.og:i;n ^ekfj: 

PRIME 

WS40 

W1B40» VAR 

) I-. :i: B I... o G .1: ?•< ^ C M I.! / 1-; 
F3:L.E BL.KS 

3t>SK ♦ 

i...OG:i:w»CM)t:" j. 

1 



The )LJS system command is an inquiry command that displays a list of 
workspaces in your disk area. )LIB assumes that any file in your disk 
area with the extension or file type .APL, contains a workspace. 

You can use the )LIB command to list the names of all or selected 
files on any directory device. These files need not be APL workspaces. 
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If you specify the wsname, you can specify the filename or file type 
to be displayed. You can identify a particular file or use the 
"wildcard" character, the asterisk, to substitute for the filename 
and/or extension or type. The asterisk matches any name. For example, 
this command lists the names of all files that have WS^■0 as their 
filename: 

This command lists the names of all files on device DSKH:. 

)\...XB PSKHJ ji; , )l[ 

The optional switch-list parameter is used to obtain information about 
files on directory devices. A description of all switches supported 
with the )LIB command are listed in Table 5-2. You can specify more 
than one switch, but each switch must consist of a slash (/) followed 
by one of the letters shown in the table. The information returned is 
displayed on the same line as the filename. 

Table 5-2 
)LIB Switches 



Switch Meaning 



/A Access: the date the file was last read (disk only) 

/B Blocks: the number of blocks required for the file 

(Divide the number of blocks by four to determine 
pages. ) 

/C Creation: The creation date of the file (disk only) 

/L Long: same as typing /B/P/C 

/M Mode: the mode in which the file was written (disk 

only) ; TOPS-10 only 

/N No header: suppresses printing of the display header 

line 

/P Protection: the protection code associated with the 
file (disk only) 

/T Time: the creation time of the file (disk only) 
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5 .2.4 )LOAD - Retrieving a Workspace 

Command 

)LOAD magtape-position I wsname HpasswordI 

Examples 

)L.OAr. W1H35 
SAVED 15:49:56 11 ■••vJUi„...79 2K 

)L.OAri LlBl ♦ AFUSF 

SAVEx:. 9:52:57 i;?-- SEP ••■■77 4K 
)i...QAx;i pr:i;mI:;: 

SAVED 14:52:57 11 HJI.......79 5P 

)i...oa.t;' aver 
SAVED 15:45:03 24-o<:-T--78 5^ 

The )LOAD system command is an action command that retrieves a work- 
space from a secondary storage device. When you load a workspace, it 
becomes your active workspace, replacing the currently active work- 
space and destroying its contents. You must specify the name of the 
file in order to retrieve it. However, APL assumes the rest of the 
wsname; that is, it assumes .APL as the file type or extension, disk 
as the storage device, current user directory and a null password (-) . 
If a password was submitted when the workspace was saved, you must 
specify it, or APL will not retrieve the workspace. 

If the workspace is stored on magnetic tape, you can specify the num- 
ber of tape marks to skip before APL tries to load the workspace. The 
magtape position is an integer corresponding to the number of end-of- 
file marks to skip on the tape. 

When you load a workspace the )LOAD system command responds by dis- 
playing the word SAVED, followed by the time and date when the work- 
space was saved, followed by the size of the newly active workspace. 
If the newly active workspace contains a suspended function, APL also 
prints an asterisk (*) . 

The UQLD system function, Section 4.3.9, performs the same operation 
as the )LOAD command, except without verifying messages. 
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5.2.5 )PASSWORD - Determining the Workspace Password 
Command 

)PASSWORD [[password]] 
Examples 

) F=' (;^ s s w o |:;: ][:• ■ s e s a m i-;: 

WAS •■•■ 

)l"ASSWORi:' 

-SESAME 

)l"ASSWORX:i ■ 
WAS -SESAME 

) FAS SWORD 



The )PASSWORD system command allows you to either display the current 
password associated with a workspace or change the password. The 
password parameter you supply must begin with a hyphen and can contain 
up to eight more characters from A-Z, A-Z-, A, A, 0-9; the first char- 
acter after the hyphen must be alphabetic {A-Z, A-Z, A, A). The 
default or null password is a hyphen (-) . 



5.2.6 )SAVE - Saving a Copy of the Active Wor kspace 
Command 

) SA VE H magtape-position II Iwsname N llpassword 
Examples 

) ws:i:d 

CLEAR ws 

)SAVE 

^'(■J w II.; H o r i:> <^^ V i:-: x:i 5, r i-i .1: *•> w o h: k s i"- a a iii: :i: s c 1... e a i=i: w s 
)ws:i:x:i WS30 

WAS CI...EAR ws 
)SAVE 

16t0BtA0 :l.:l. HJ1...-.79 :|. pgs ws30 \::Ay20Al 

)ws:i:x:i wsj. 
was WS30 i:;4y204.':i 

) SAVE 

i.6?08j;:^:i. :i.:i.- -"•^'-■•79 :i. '^^•(:^^;> wsio i:4>-204::i 

)ws:i:d WS30 

WAS ws:i.o i:;4i'204::i 

)SAVE WS:|, 

S w s a o T s f^ V I:-: .o y r i-i :i; s w o i-i: k <:> i-- a c i;:: :i: s w s 3 |;; 4 y 2 <) 4 ::i 
) w If; :i: p w i:> 3 5 
w A *:> w s 3 1;: 4 y 2 4 1 

The )SAVE system command is an action command that saves a copy of the 
active workspace on a secondary storage device. The saved workspace 
can be stored as a file on disk, DECtape^ or magnetic tape. 



^Some systems do not support DECtapes. Check with your System 
Administrator . 
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The )SAVE system command assumes that you want to save your active 
workspace on disk. All three parameters in the command string are 
optional. If you specify a wsname, )SAVE stores the active workspace 
under that name. The default wsname is the name of the currently 
active workspace. In both cases, the file type or extension is .APL. 
The protection code is the standard one for your installation. As 
shown in the first example, APL will not save a clear workspace. If 
your workspace is clear, you must use )WSID to give it a name before 
you can use the )SAVE command. 

If you are saving a workspace on magnetic tape, you can also specify 
the position at which the save is to start. The magtape-position 
parameter in the command string is an integer representing the number 
of end-of-file marks you want to skip before the save begins. If you 
omit this parameter, APL makes no attempt to position the magnetic 
tape. For example: 

) s A V b: 3 M r- <:^ i j w s 3 >■■, 
16 J 26^49 :l.;l. nji..,....79 3 bi...ks 



In the example above, APL skips three tape marks before it starts to 
save the workspace. 

When you save a workspace, you have the option of saving it under its 
current name (check the )WSID) or renaming it. However, you cannot 
save a workspace under a name that already exists in your storage area 
unless the )WSID is that name. APL refuses to save the workspace. If 
you specify a new name with the )SAVE command, you not only store your 
active workspace under that name but also change the name of the cur- 
rently active workspace to the new name specified. 

NOTE 

If your current )WSID is the same as a 
workspace you have already saved and you 
save it under this name, APL overwrites 
the old file with the new one. 

The )SAVE system command also provides the option of specifying a 
password for your workspace. The default is a null password (-). 
Subsequently, you must know the password of the workspace to retrieve 
it from storage. 

If you interrupt a function execution by typing two CTRL/Cs and then 
save your workspace, the function is suspended in your storage area. 
Therefore, when you load this workspace, the function does not con- 
tinue automatically. You can cause an automatic start-up by using the 
ULX system variable (Section 4.2.13). 

If you execute a )SAVE command within £i function, for example, <. 
')SAVE', APL saves the workspace and continues executing the function. 
The next time you load that workspace APL will begin the session by 
executing that particular function at the line after the c ' ) 5.4 1'E" ' . 
APL will not execute []LX in this instance. ULX executes only if there 
is a suspended function on top of the )SI stack. 

The )SAVE command responds by displaying the time, date, and amount of 
space required to store the workspace. If you have not included the 
wsname, APL also displays the current name. 
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5.2.7 )WSID - Identifying the Active Workspace 

Command 

)WSID [[wsname nil pas sword 11 

Examples 

) W <:J X D VS K * M Y W O R K , A l=- 1... 
WttS CLEAR WS 

)\»sxr^ 
MY WORK i:;4s<204."i 

)WS.i:.t.' MTA.lt 

w A s M Y w o i-i: i< I" 4 y 2 4 :;i 

) ws:i;d 

M Tf- A :|. * M r- W O I-:: l< |" 4 y 2 4 II 

)ws:i:x;.[:4,3ii:i 
w A B M r A :|, * M Y w o I-: K I" 4 y 2 4 .:i 
) ws:i:x.-< 

MY WORK |;;4 J, 3:|. i ;:i 



The )WSID system command can be used as either an action command or 
inquiry command. As an action command, )WSID allows you to change the 
name and password of the active workspace. As an inquiry command, 
)WSID returns the name of the active workspace. When you use )WSID as 
an action command, you must specify the wsname parameter. However, 
you need not specify the entire name. APL uses the defaults listed in 
Table 5-1. With )WSID you can also specify a password parameter. This 
causes the password associated with the active workspace to be changed 
to the specified password. The )PASSWORD system command (Section 5.2.5) 
allows you to change only the password. 

As shown in the examples above, the )WSID system command returns a 
workspace name when used either as an action command or as an inquiry 
command. When )WSID returns a workspace name it always returns the 
workspace filename. Those additional parts that are the same as the 
defaults are not displayed. The password is never displayed with 
) WSID . 



5.3 EXTENDED WORKSPACE-CONTROL COMMANDS 

This section describes a variety of system commands that extend the 
basic workspace-manipulation functions detailed in Section 5.2. These 
commands can be used to: 

1. Determine the maximum and minimum size of the active workspace 

2. Report workspace owner and version information 
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3. Turn the workspace lock on and off to control access by other 
users 

4 . Report how long the active workspace has been in use 

5 . Determine how large the active workspace would be on a 
secondary storage device 



5. 3.1 )MAXCORE - Determining the Maximum Workspace Size 
Command 

)MAXCORE 



i K-of -memory ) 
\ P-of -memory / 



Examples 

rt TOPS ...1,0 
) MAX CO RE 

20'</ :l.76i< 

)MAXeORI::: ^O 

WAS 20'< 

H TOPS.. ..20 
)MAXCOHi:H 

) MAKCORi;:: 70 
WAS 40 1"' 

The )MAXCORE system command can be used as either an action command or 
an inquiry command. As an action command, )MAXCORE changes the cur- 
rent setting for the maximum workspace size to the amount you specify 
and displays the previous setting. As an inquiry command, )MAXCORE 
should be typed without a parameter; it returns the current maximum 
workspace size and the system memory limit for the data segment. 

The standard APL default is 2 OK words for the data segment on TOPS-10 
and 4 OP words on TOPS-2 0. The maximum value for K-of -memory is either 
176K words or the system memory limit, whichever is smaller. The 
maximum value for P-of-memory is 352P words. Note that you do not 
type P or K in the command string. 
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5.3.2 )MINCORE - Determining the Minimum Workspace Size 



Command 



)MINCORE rr |K-of -memory ^-n 
U \P-of-memory/ JJ 



Examples 



OK 



flTOPS....;|.0 

)m:i:hcork:: 



)M:i:HcoHi:E :| 

WAS ()'< 

n TOPS. ...20 

)M:i:f<CORI::: 

OP 

)m:i:ncori::: 35 

WAS ()'"■ 



The )MINCORE system command can be used as either an action command or 
an inquiry command. As an action command, )MINCORE changes the cur- 
rent setting for the minimum workspace size to the amount you specify 
and displays the previous setting. As an inquiry command, )MINCORE 
should be typed without a parameter; it returns the current minimum 
workspace size. The standard APL default on both operating systems 
is 0. Note that you do not type P or K in the command string. 

NOTE 

APL does not allow you to specify a 
minimum workspace size that is larger 
than the setting of )MAXCORE . 

The )MINCORE system command is very useful in dealing with very large 
arrays or with operations requiring large amounts of intermediate 
storage that cause the workspace to expand and contract. )MINCORE 
causes APL to retain at least the amount of memory specified and thus 
to speed up operations by precluding the frequent acquisition and 
release of large blocks of memory. 
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5.3.3 ) OWNER - Identifying the Owner of a Workspace 
Command 

) OWNER 
Example 

) OWNEI-i: 

CFi:EATi;;:i:> ON :|.2 JIUI....-79 .by 1:4 y 2043 f-^'i' "I"'!'"'' 22 



The ) OWNER system command is an inquiry command that displays infor- 
mation about the creation of the currently active workspace. ) OWNER 
returns the date on which the workspace was created, the directory of 
the creator of the workspace, and the terminal number of the device 
at which it was created. 



5 .3.4 )SEAL - Turning the Workspace Seal On or Off 



Command 



)SEAL 



[off] W 



Examples 










)S 


EAL. 




OFF 










)S 


EAI... 


OH 


WAS 


OFF 







The )SEAL system command is both an action command and an inquiry 
command. When you use it as an action command, you can turn the work- 
space seal (lock) on or off. The default setting is OFF. When the 
workspace seal is on, only the user who turned the seal on can copy 
objects from the workspace or turn the seal off. The )SEAL command 
has no effect on the )LOAD command. 

As an inquiry command, )SEAL without a parameter returns the current 
setting of the seal. 
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5.3.5 )SIZE - Reporting the Workspace Size 



Command 



)SIZE 



Examples 



flTOPiiJ-20 
)s:i:zi::: 
35P :i. PGS 



ft TOPIS-. ;|.o 
)s:i:zii:: 

3K 2 1K<I-I<"> 



The )SIZE system command is an inquiry command that displays infor- 
mation on the size of the active workspace. )SIZE returns two numbers 
the first is the current size of the data segment, the second is the 
amount of disk space that would be required to store this workspace 
if it were saved in its present state. 



5.3.6 )TIME - Reporting the Time Used 



Command 



)TIME 



Examples 



) CI... EAR 

cl..ki:ap ws 

)t.-i:me 
eoHHECTii-x:. J 00 J 04 cpu t:i:mi:!: J 00 J 00 

) i...ofti:i pr:i;me 

s A V E x> ;|. 4 ? 5 2 J 5 7 I ;l. -■ -■• i-^ i- •••• 79 35 1"' 
)t:i:me 

co?<HECTEx:. o::l.8J;lO <"'==• i-^ t:i:me J 00 J 03 



The )TIME system command is an inquiry command that reports the amount 
of connect time and CPU time accumulated while the currently active 
workspace has been active. This command is useful in determining the 
amount of time expended by programming projects. The time begins to 
accumulate when the workspace is created as a clear workspace, and runs 
until the session is terminated or the current workspace is saved. 
The )COPY command does not affect the time accumulation. 
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5 .3.7 )VERSION - Displaying the APL Version Number 
Command 

) VERSION 

Examples 

) VERS :i: ON 
2 ( 4 :l. 2 ) 



The ) VERSION system command is an inquiry command that displays the 
APL version number with which the currently active workspace was last 
saved. If your workspace is a clear workspace, APL prints the current 
version of the interpreter, in the format ver(edit#) where edit is in 
octal . 



5.4 WORKSPACE-CONTENT COMMANDS 



This section describes the system commands that examine and control 
workspace elements such as functions, variables, and groups. The 
following operations can be performed: 

1. Copy variables, functions, and groups from a stored work- 
space, and erase these elements from the active workspace 
when desired 

2. Display a list of functions defined in the active workspace 

3. Collect named objects into a group, disperse the group, dis- 
play the members of the group, and display a list of groups 
defined in the active workspace 

4. Display the APL state indicator to report on the execution of 
functions in the workspace 

5. Display a list of variables defined in the active workspace 
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5.4.1 )COPY - Copying Objects from a Wo rkspace 
Command 

)COPY wsname |[passwordJH[named-object-list]j 
Examples 

)CD|:iY AVER 

SAVED :|.5M5J03 24 •••<:»:• ■'■■■78 35"==- 

)COPY AVER Vf 

SAVEx:. :l.5t45:03 24 -<:":• ^■- 7 8 35i==- 

)CO|--Y AVER C 

SAVED :I.5I45:03 24 -o (:••'■■■■• 7 8 35i==- 

OBJECTS NOT FOUHI.i ♦ C 



The )COPY system command is an action command that retrieves functions, 
variables, and groups from a stored workspace and places them into 
your active workspace. If there is a password associated with the 
workspace, you must include it in the command string. You have the 
option of copying all the named objects in a workspace or a subset of 
them. The named-object-list identifies the specific objects to be 
copied. If you omit this parameter, all user-defined functions, vari- 
ables, and groups are copied. 

)COPY does not transfer local values for variables and functions, nor 
does it copy the state indicator, the width, origin, and significant- 
digits setting. Only global values of user-defined objects are copied, 
since a )COPY writes a fresh user symbol table. That is, if A is a 
local variable with a value of 3 and a global value of 15, APL copies 
the global value 15. Also, if your active workspace contains objects 
with the same name as those in the copied workspace, APL replaces the 
global values in your active workspace with the copied ones. For 
example, if 5 is a variable in the active workspace with a global 
value of 10 and a local value of 5, and the workspace being copied 
has a variable B with a global value of 2 after the )COPY , the active 
workspace will have a variable B with a global value of 2 and a local 
value of 5. Objects that have the same name in both workspaces but 
are pendent functions or functions still being defined are not replaced 

When you copy a group, all members of the group are copied along with 
their values. However, if a member of a group is itself a group, APL 
copies only the group names and not the values from this level. 

If you specify an object that is not located in that workspace, APL 
returns a message OBJECTS^NOT FOUND, 

The )COPY command is the same as the UQCO system function except that 
UQCO does not display messages to confirm that the copy was success- 
ful. See Section 4.3.9 for UQCO information. 
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5.2.4 ) ERASE - Erasing Global Names 

Coininand 

)ERASE name-list 

Examples 

'^^'^^ 3 4 

A 

2 3 A 

A 
:|. I VAL..UI::: EFirROfi: 



VRfF 
111 ) ERASE F 

NOT ERASEnj 

1:1:3 



The ) ERASE system command is an action command that erases global 
names from the active workspace by undefining the functions, vari- 
ables, and groups specified in the name-list parameter. You can 
undefine a suspended function but not a function in the process of 
being defined. If you specify a group name, then the group name is 
erased from the active workspace along with the members of the group, 

If a member of the named group is itself a group, the group name is 
erased but the members of the subgroup remain intact. For example: 

) FHS 
ARC CDS DXAM RAXI'IIIUS SXJi TAN 

)GRI"- TRIG 

ciFirci..!-;: COS s;i;n tan 

)ORR CIRCLE 
ARC XI'-CAM RADIUS 
) ERASE TRIG 

)ORR tr:i:cj 
2 2 •'• '-^ <" <•> '■*: '■': '•■• <•■ If' '"■ ^ '•'• f-^ M ^- ">' f"- f'- 

)GRR TR.TG 

A 
)GRP CIRCLE 
2 2 •'• >■* <•• <•> '■•: ^'•' '••• <•■ If' '"■ f^ '•'■ '^^■> M E r- 11;: |:i: 
)ORP CIRCLE 

A 
)FNS 

A R c x:i :i: n m i=i: n t< xu s 



The ) ERASE command does not distinguish between pendent functions and 
other functions. You should avoid erasing pendent functions because 
of problems you could create. APL attempts to alleviate such problems 
by displaying the following message after performing the )ERASE 
operation : 

:| 3 POSSIBLE SI DAMAGE 
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This warns you that remedial action might be required before execution 
of the function continues. {SI refers to the state indicator.) 

Note that ) ERASE leaves a slot in the symbol table for the erased name 
(symbol) . Although you erase a symbol, the slot in the symbol table 
still exists. If you reuse a name that was in the symbol table, APL 
places it in the same slot where it was before. If you do a )COPY of 
the workspace, APL rebuilds the workspace thus erasing the slot as 
well, as the symbol. 



5.4.3 )FNS - Displaying a List of Functions 
Command 

)FNS |[letter| 
Examples 

AI...PH h:i:i...b :i: :i:nv us« 

)FNS x 

X :i:hv i.„ii>a 

The )FNS system command is an inquiry command that displays an alpha- 
betic list of global names used as user-defined function names 
(Chapter 6) in the active workspace. The optional letter parameter 
identifies the letter at which the alphabetic listing is to begin. If 
you omit the letter the entire set of global function names is dis- 
played. 



5.4.4 ) GROUP - Defining or Dispersing a Group 
Command 

) GROUP group-name llgroup-member-list I 
Examples 

) G P: <:> u p I"- X ti A w c X f^ I... :i: it r f u r u (■>> i... i-- r: i-i: s v a i... 
) G R o u I"- I-- :i: r< f>, h c x t^ i... t a x f x n f>, m c x a l. 

) G 1=:.- O U F'- F X N A H C X A L. 
) Cv Hi: O I) I-- I-- X M A H C X A I... )•( 

The ) GROUP system command is an action command that places a collec- 
tion of named objects under one group name and can disperse an exist- 
ing group. The objects can be variables, functions, and other group 
names. The ) GROUP command is used primarily with the )COPY and 
)PCOPY commands. After collecting a set of functions and variables 
under one group name, you can specify this name in a )COPY or )PCOPY 
command to copy the entire collection at one time. In the first 
example above, the functions and variables named INT, FUTUAL , and 
PRESVAL are collected into a group named FINANCIAL . 

To add a new member to an existing group, you must list the groupname 
as an element in the member list. This is illustrated in the second 
example where the variable TAX is added to the group named FINANCIAL . 
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To disperse a group, specify the group name without a group-member- 
list. The group name will no longer be defined but the individual 
members of the group still exist under their original names. The 
third example above disperses the group FINANCIAL . 

A group name is always global; you cannot localize it. For example 

Vfi-2 

[I ;;| ^ > ) GROUP C A B > 

121 '^ 

I"' 

24 a HOT OROUPEX:' j, namih: xh use 

) GROUP C A B 



5.4.5 )GRP - Displaying the Members of a Group 

Command 

) GRP group-name 

Examples 

) o y--: o u I"- F :i: t> n h c :i: f>i i... :i; n r f u i' u a i... f- r i-;: s v (a i... 
) GRP f:i:nanc:i: Ai... 
:i: H r y- u r u a i... i-- f-: i:-; s v (^ i... 

The )GRP system command is an inquiry command that displays the mem- 
bers of the group named in the command string. The members are 
listed in the order in which they entered the group. 



5.4.6 )GRPS - Displaying a List of Groups 



Command 

)GRPS [[letter]] 
Examples 

) ORPS 

F X ti A >•< c^ X A I... :i; M V III; n r o i=:: y 

inNVENTORY 

The )GRPS system command is an inquiry command that displays an alpha- 
betic list of global names you specified as group names in the active 
workspace. The optional letter parameter identifies the letter at 
which the list is to begin. If you omit the letter, the entire set 
of group names is displayed. 
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5.4.7 )PCOPY - Copying from a Workspace with Protection 
Command 

)PCOPY wsname password ||f[named-object listH 
Examples 

l"I...USROWf40 

)PCOr=Y MY WORK F F-I...USROW PRIMES A 

SftVEx;. l0t2At30 :l.2 njL....79 35P 

}■>. o T c o r-- X b: x:' ♦ a i-- l u s i-: o w 

)PCOPY MY WORK G B F 

SAVii-x:. ;|.0?24J30 J. 2 MJL....79 35P 

OBJECTS HOT FOUNXH ♦ G 

HOT cop;i:ex;>* f 

The )PCOPY (protected copy) system command is an action command that 
performs in much the same way as the )COPY system command. However, 
)PCOPY protects you from accidentally replacing objects in your active 
workspace, that is, )PCOPY does not replace objects in the active 
workspace with objects of the same name in the copy workspace. In- 
stead, APL returns the message NOT COPIED: along with the names of the 
objects involved. 

When copying groups, the )PCOPY command does not copy any members of 
the group that have the same name in the active workspace. If the 
group name itself is the same as a group name in the active workspace, 
APL does not copy the group name but does copy any member of the group 
that does not have the same name in the active workspace. 

Named objects that cannot be found in the copy workspace or cannot be 
copied are displayed as shown in the examples. 

The )PCOPY system command operates the same as the UQPC system function 
except that UQPC does not return messages to verify the success of the 
copy. See Section 4.3.9 for information on UQPC. 



5.4.8 )SI - Displaying the State Indicator 



Command 

)SI 
Examples 

\:\x 






<^=[:2::i « 
<sr:3:;i 

The )SI system command is an inquiry command that displays the state 
indicator of the active workspace. The state indicator contains the 
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status of the execution of user-defined functions in the workspace. 
By analyzing the )SI listing, you can determine such function-status 
conditions as the following: 

1. suspended functions (*) 

2. pendent functions 

3. pending quad input requests 

;:iig|j|||i|iiiiiip||iB^ 

A bracketed line number following the function name indicates the line 
at which the function stopped executing. An asterisk following the 
bracketed line number indicates that the function is currently sus- 
pended. If there is no asterisk, the function is a pendent function 
(one awaiting the return of a called function) . 

Instead of a line number, the )SI display can contain only an asterisk 
(*) , a quad character (D) , liii'MifcyigiialiilliiSiiffiliK^ In this 
case, an asterisk indicates that a suspended function has been erased. 
A quad character indicates pending quad input. An execute function 
indicates an execute operation. 

The order in which functions are displayed in the )SI list is signi- 
ficant; the function that was most recently active is listed first. 



5.4.9 )SIV - Displaying the State Indicator and Local Variables 
Command 

)SIV 
Examples 

) S X V 

F|;;;>l n r a b 

^lil A T c A D 



The )SIV system command is an inquiry command that acts much the same 
as )SI. However, )SIV also displays a list of variable names local to 
the halted function including localized system variables. The )SIV 
command displays the status of pendent and suspended functions, pend- 
ing quad input requests, and operations involving the execute operator, 
Unlike )SI, )SIV also displays the current line of any pending execute 
string. 
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5.4.10 )VARS - Displaying a List of Variables 



Command 

)VARS [[letter]] 



Examples 


) VAKS 




A 


:i: 






) VAHi:S 


K 


i< 


H 





The )VARS system command is an inquiry command that displays an alpha- 
betic list of global names used as variable names in the active work- 
space. The optional letter parameter identifies the letter at which 
the listing is to begin. If you omit the letter, the entire list of 
global variable names is displayed. Local variables are not listed. 



5.5 WORKSPACE-ENVIRONMENT COMMANDS 



This section describes a variety of system commands that allow you to 
control the characteristics of the workspace environment. These 
commands can be used to: 

1. Specify the maximum number of significant digits to be 
displayed 

2. Determine the index origin setting 

3. Determine the terminal output mode, displaying error lines, 
setting terminal tab stops 

4. Set or return the width of the output line 



5.5.1 )DIGITS - Determining the Output Precision 

Command 

)DIGITS Jn]] 

Examples 

) V :i: Cv :i: r s 
1 

:l. «23456789:l.234S6789 
:L. 23456789:1. 

) xi' :i: (•■ 5 
w A s X 

1 *234567891.234S6789 
:L<.2346 
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)v:.;i:g 2 

W A S 5 

1. .23456789:1.23456789 
1*2 



The ) DIGITS system command is both an action command and an inquiry 
command. As an action command, ) DIGITS allows you to specify the 
maximum number of significant digits you want APL to display for 
noninteger output only. As an inquiry command, ) DIGITS displays the 
current setting. The parameter n can be from 1 to 18; the default 
setting is 10. 

APL rounds off a number if it has more digits than the current 
setting. 

The ) DIGITS system command does not affect the precision of internal 
calculations or the display of numeric constants. The setting is 
preserved when you save the active workspace. 

The ) DIGITS command performs the same operation as the DPP system 
variable (Section 4.2.15). 



5.5.2 )ECHO - Determining Error Line Echoing 



Command 

)ECEO 



iON ) 
\\OFF)]_ 



Examples 

) Hi:ci-io 

ON 



WSSW^S0$:i^W^^M: 
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)i:i:cHO OFF 

WAS ON 



.«. 



e\ ' 



2;^ ii::;;ecuti:=: frrop: 

The )ECHO system coiranand is both an action command and an inquiry 
command. As an action command, )ECHO allows you to select whether or 
not to have APL echo statements that contain errors. As an inquiry 
command, )ECHO returns the current state of echoing. The parameter is 
either the word Oil/ or the word OFF. The default is ON. 

If the echoing status is OFF and you perform an execute (e or 1; 
operation (Sections 3.4.3 and 5.8), APL prints neither the error 
message nor the error line. The value of the execute expression is a 
null array of rank two. The first dimension of the null array is zero 
and the second is a number that identifies the type of error encount- 
ered (see Appendix A) . This feature aids the handling of error con- 
ditions under program control and is illustrated in the final example 
at the beginning of this section. 

The echoing status is preserved when the active workspace is saved. 



5.5.3 )MODE - Determining the Terminal Output Mode 



Command 



)MODE \\iESCAPE \ 

\j{keywordI 



Examples 

) MODE 
KEYWORD 

)MDDE ESCAPE 
WAS KEYWORD 

A_..'{f?AG?K(»K(3Z' 

A 

eAa»z 

)MODE KEYWORD 
WAS ESCAPE 
A 

♦AL' ♦RU 

The )MODE system command is both an action command and an inquiry 
command. As an action command, )MODE allows you to select the mode of 
output on terminals that do not have an APL character set (see Section 
1.3). As an inquiry command, )MODE displays the current setting. 

The parameter can be either the word KEYWORD or the word ESCAPE. 
Either word can be abbreviated to one letter. In ESCAPE mode, on 
output, (Sp, @K, (SQ, (ay, print as *, ', ?, ". The default is KEYWORD. 
This setting has effect only if you responded to the TERMINAL.. 
prompt, at the beginning of the session, with TTY. 

The mode setting is preserved when the active workspace is saved. 
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5.5.4 ) ORIGIN - Determining the Index Origin 



Command 

) ORIGIN [[n| 

Examples 



oi-;:;i:g:i:n 



1 

IS 
12 3 4 5 

) (.) R :i: G ;i; m o 
WAS :t. 

\5 
12 3 4 



The ) ORIGIN system command is both an action command and an inquiry 
command. As an action command ) ORIGIN allows you to change the 
setting of the index origin for array operations and returns the 
previous setting. The parameter "n" can be either or 1 . The de- 
fault setting is 1 . As an inquiry command, ) ORIGIN displays the 
current setting. 

The effect of the ) ORIGIN command is to renumber the elements of 
arrays to begin at or 1 , depending on the setting. This command is 
particularly relevant when used with the i function. (Sections 3.3.10 
and 3.3.11.) The index origin setting is saved when the active work- 
space is saved. 

The ) ORIGIN system command performs the same operation as the UIO 
system variable (Section 4.2.11). 



5.5.5 )TABS - Determining Tab Stops on the Terminal 



Command 

)TABS [[n]j 

Examples 





WAS 



) TABS 
)TABS 9 



The )TABS system command is both an action command and an inquiry 
command. As an action command, )TABS sets the increment between tab 
settings for APL output. As an inquiry command, )TABS returns the 
current tab setting. The integer parameter "n" specifying the tab 
increment can be from to the page width. The default setting is 0, 
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If you reset the page width with either the UPW system variable 
(Section 4.2.16) or the )WIDTH command (Section 5.5.6), the )TABS 
setting is reset to the new page width. 



For example : 



i:;|pw 
72 

)TAx;<s 70 

WAS {.) 

n'==WfSO 

>TABS 
50 

)w:i:x;'TH 45 
WAS 50* 



The asterisk in the above example indicates that )TABS has been reset. 

NOTE 

The )TABS system command is designed for 
use on terminals with physical tab stops. 
The tab setting is not saved with the 
active workspace. 

APL will output a TAB instead of a string of blanks if the next non- 
blank character to output comes after a tab stop. 



5.5.6 ) WIDTH - Determining the Width of the Output Line 
Command 

) WIDTH |[n]j 
Examples 

) w:i:x.vrH 
72 

\15 
1 2 3 4 5 6 7 B 9 10 11 12 13 14 15 

) WXDTH 
WAS 72 ft 

•(15 

12 3 4 5 6 7 8 9 10 11 12 13 

14 15 
) w:tx:iTH 

30 



The )WIDTH system command is both an action command and an inquiry 
command. As an action command, you can set the maximum number of 
characters that can appear in an output line and display the previous 
setting. As an inquiry command, the ) WIDTH command returns the 
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current width of the output line. The parameter "n" must be an 
integer within the range 30 .through 390. The default is determined 
by the system width setting. You can change the system width for 
your current job at operating system command level by using: 

^TERMINAL WIDTH lTOPS-2 

.SET TTY WIDTH lTOPS-10 

The ) WIDTH system command does not affect the display of messages on 
the terminal or the allowable length of input lines. The width set- 
ting is preserved when you save the active workspace. 

The ) WIDTH system command performs the same operation as the UPW 
system variable (Section 4.2.16). 



5.6 APL TERMINATION COMMANDS 

This section describes the various system commands that can terminate 
an APL session. You can exit from APL in a variety of ways. You can 

1. Terminate the session, save the active workspace, and run a 
program 

2. Terminate the session and save the active workspace 

3. Return to system command level 

4. Terminate the APL session, optionally returning to system 
command level 

5. Terminate a session and run a program 



5,6.1 )C and )CALL - Running a Program and Returning to APL 
Command 

)C llnjl file specification- 

)CALL [[njl file specification 
Examples 

)<:.-. M...\... SrS X FORTRA 

*,TTY? - TTY J 

:i: ^--^ X 

END 



MAIN. FORTRAN V <■ l^iiA ( 62:1. ) /KI :!.2- JUL-79 ISJOO 

PAGE 1 



0000:1. :i: ••=■•: :i. 

00002 END 



SUBI-'ROGRAMS CALLED 



5-32 



SYSTEM COMMANDS 



SCALARB AND ARF;;AYS I "t" NO li^XPLICXT DE FINITiliON - "%" NOT REFERENCED 1 

>!( :i: :i. 

MAIN* i:: NO ERRORS DETECTED 1 
t R I J N J A I"' I... S F / R LI N 1"' F S E T 1 1 

TERMINAL* a.. A 

f> f- 1... -. 2 !(;• 1:-: c <•> r' s r b m ■ .• 2 (> f^ f- 1... s f 2 < 4 :L 2 ) 

If TV 22) :l. 3* 01 J 33 THURSDAY 12 MJI......79 masi:i:l.l.a I:4!-204:J 

CL-KAFi: WS 

The )C and )CALL system commands perform the same operation as )R and 
)RUN except that )C and )CALL also save your active workspace as 
CONTIN .APL. They also write an APL .TMP file {nnnAPL.TMP) or .TMPCOR 
file so that, if APL is subsequently run with a CCL linkage, the 
processor is able to determine the terminal type from the file written 
and does not prompt you with TERMINAL . . . 

The difference between )C and )CALL is the default device searched. 
The )C command defaults to SYS:. The )CALL command defaults to DSK:. 



5.6.2 )CONTINUE - Saving the Workspace and Ending the Session 

Command 

) CONTINUE ^HOLD^ 

Examples 

) coht:i:huk:: hoi...d 
9? 35 J 53 :l.2 MJI...-.79 2 bi...i<s 

TTr44) 9 J 35 J 54 :l.2 •"UI.......79 

c: o ii M lii: c r III: x:> () * q ;|. * 4 9 c r-- u r :i: m ni; q ^qq* q q 
s r (>i r III: m hi: h t s q o r- 111: r a r :i: o ti <i> 
K :i: I... o ■■■■ c o i=i: III: •• • <i> 111: c s ;|. 3 

EXIT 



The )CONTINUE system command is an action command that ends an APL 
session after saving the currently active workspace. )CONTINUE 
operates the same was as )OFF (displaying the same statistics) except 
that before ending the session )CONTINUE saves the active workspace in 
your disk area under the name CONTIN .APL . The workspace is saved 
only if it is indeed active, that is, contains at least one symbol in 
the symbol table. The saved workspace replaces any other disk file 
that you previously saved with the name CONTIN .APL. 

The next time you begin an APL session, instead of a clear workspace, 
you will receive the CONTIN .APL workspace as your active workspace. 

The HOLD parameter returns you to operating system command level 
after ending the APL session. )CONTINUE not only prints the same 
summary information as the )OFF command, but also displays an initial 
line that specifies the time, date, and size of the saved workspace. 
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5.6.3 )MON - Returning to Operating System Command Level 
Command 

)MON 
Examples 

fl TOPS ■•20 

) MON 

MONITOR' ♦ 
(flCOHTXHUE 

APLSF * 

fiTOr=S....10 
) MOM 
MON.ITOR ♦ 

.REENTER 



The )MON system command is an action command that returns control to 
operating system command level. The )MON command does not save the 
active workspace as the )CONTINUE HOLD does. Therefore, if you in- 
tend to return to APL and save the workspace, be careful not to destroy 
your memory image while at command level. This could occur if you 
issue a command that runs a program. 

You can return to APL by typing the operating system command CONTINUE 
or REENTER. For more information on returning to APL, refer to 
Section 1.4.4. 



_5^6.4 )OFF - Terminating the APL Session 
Command 

)OFF \eOLI)\ 
Examples 

) OFI"' 

•"••^22) :l, 5: 40:22 ;l.2- -'i-""-79 

cowN'ECTi:i:x:. J 00: 34 ("•==i-' t:i:mii:: o: 00 J 01 

t^ STftTEMKNTS <f> O P E R A T :i; O N <•> 

KILLED JOB 16 V USER MASELLAy ACCOUNT APL y TTY 22 y 
AT :l.2-JUL--79 ;I.SM0t22y USED : H. IN 0t0:42 

)OFF HOI...X:i 

■IT •"• 'If' 2 2 ) :i. s 1 4 :i. : 1 e 1 2 •••• -• i-J •■•• • - 7 9 

(- o H H !;•: <:: r- lii: x:. J : :l. 9 "^^ '''■ i ••' f :•: m "^ J J 

STATEMENTS OPI-irR AT l ONS 
EXIT 

The )OFF system command is an action command that terminates your APL 
session. If you specify the EOLI) parameter, APL terminates your 
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session and returns you to operating system command level. Without 
the BOLD, APL not only terminates your session but also logs you off 
the system. 

The )OFF commands outputs several lines of information before termin- 
ating the session. The lines contain the following: 

1. Your terminal identification 

2 . Current time 

3 . Current date 

4. Length of time connected to APL 

5. Amount of computer CPU time used 

6. Number of statements 

7 . Number of operations executed 

8. Kilo-core-seconds-used (TOPS-10 only) 

The )OFF command destroys the currently active workspace. 

5.6.5 )R and )RUN - Ending the Session and Running a Program 
Command 

)R [[nJI file specification 

)RUN [In file specification 
Examples 



i;;:x;i;t 



Kuw DSK ♦ 7i;::i;rr 



)R FORTRA 



The )R and )RU'N system commands perform essentially the same function 
as )OFF BOLD. They terminate the current APL session and return you 
to the operating system, but unlike )OFF BOLD, they also run the 
program you specify as the filespec in the command string. The file 
you specify must contain a program ready to run, that is, a program 
with a file extension or file type of .EXE. The optional parameter 
"n" is an integer value that is added to the starting address of the 
file to be run; this facility is useful when starting from alternate 
entry points (for example, CCL entry points are equal to 1) . 

The )R and )RIJN commands do not save the currently active workspace 
nor the reentry point to APL before ending the APL session. If the 
program you identify cannot run for some reason, you will be at 
operating system command level. 
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The difference between the )R conunand and the )RUN command is the 
default device that is searched. The )R command default device is 
SYS:. The )RUN command default device is DSK: . 



5.7 MISCELLANEOUS COMMANDS 



This section describes the additional system commands that perform such 
tasks as the following: 

1. Generating a mask to protect confidential data 

2. Displaying a record of activity during the current APL 
session 



5.7.1 )BLOT - Generating a Mask 



Command 

)BLOT [[n| 
Examples 



)BI...DT 30 



The )BLOT system command is an action command that generates a mask in 
a random pattern to conceal confidential input such as passwords. The 
optional parameter "n" specifies the length of the mask. If you omit 
the parameter, the default length is 2 5 characters. 



5 .7.2 ) CHARGE - Displaying A PL Session Information 
Command 

) CHARGE 
Examples 

) CHARGE 

TTY22) :I.SJ43t39 :l.2- -•'^•■" ••-79 

coKHECTiin:. J 00 J 35 <:.i^=-u "cx.hk OtOOJOO 

i:> r- A r I:-: m I::; h r s q o i"- i;;: i-: a t' :i: o m s 

The ) CHARGE system command is an inquiry command that displays a 
record of activity during the current APL session. Information to be 
displayed includes the statistics as the )OFF and )CONT commands 
display: 

1. connect time 

2. CPU time 

3. number of APL statements 
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4 . number of operations executed 

5. kilo-core seconds (TOPS-10 only) 

5.8 ■ SYSTEM COMMANDS "J^a THE EXECUTE FtfNCTION ':■%.?''•■: 

The execute function <e,i,±) allows you to use any system command as 
an argument, as long as you enclose the command in single quotation 
marks. The value returned by the execute is always a character vector 
or matrix. When displayed, the response of the execute function re- 
sembles the response of issuing the command by itself. This allows 
you to execute a system command from within a user-defined function. 
For example: 

n< ii < ) vARi;j ' 

A B c 

The shape of the result returned by the execute function after execu- 
ting a system command indicates the number of characters in the com- 
mand response. (Carriage returns and line feeds are not included in 
the count.) Table 5-3 lists the shape of values resulting from execu- 
ting a system command with c . See Sections 3.4.3 and 3.4.4 for a 
detailed description of APL execute functions. 



Table 5-3 
System Commands and Execute 



Response 



Rank 



Rho (p) 



no characters 

one character 

more than one character 
but only one line 

multiple lines 





null vector 

number of characters 



number of lines, current 
width 



The following example illustrates several uses of the execute func- 
tion, with comments describing the characters included in the count: 



wftis 



rtf t • )DI=::1'(5J.'H % 
A 

f A 



f,*;iiiAi"i;i: x.s '^; charaotii):!-:*!; 

f^SPAClii: :r.S a CHAKACT l::t-f: 

A< {| ' ) w i:x:iTH .i."52 ' 

A 



WAS 72 



f A 
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TTY22) l'::,tA7tA6 :l.2 n.fL.-79 

CDHHi:i:cTi;i:D ()J04M2 ^■■^■■■>^> t:i;mi;i: o:oo:0:I. 
IQ STATEMEHT?;; :|. ^ opi;;:rat3:on<:j 

3 :l.32 
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CHAPTER 6 
DEFINING AND EXECUTING FUNCTIONS 



6 . 1 INTRODUCTION 

APL language statements operate in any of three modes : 

Immediate mode (or execution mode) : in this desk-calculator 
mode, APL statements and expressions are executed immediately 
after you terminate the line. 

Function-definition mode: in this mode, you name, develop, edit, 
and save functions for use at a future time. 

Function-execution mode: in this mode, you execute the function 
you created in function-definition mode. 

The language syntax is the same in all modes. However, in function- 
definition mode there are a variety of special APL characters avail- 
able and a number of practical considerations you need to take into 
account when you construct a function. 

This chapter discusses: 

1. Function definitions, headers, and variables 

2. Editing procedures 

3. Branching and the use of labels, trace vectors, stop vectors, 
and the state indicator 

4 . Use of locked and suspended functions 

5. Error trapping 



6.2 DEFINING THE FUNCTION 



APL provides a comprehensive facility for defining, changing, and 
calling user-defined functions that supplement the large set of 
primitive functions discussed in Chapter 3. Once you write or define 
a function, you can save it and recall it with the ease of a primitive 
function. 

You construct a user-defined function in two parts, a function header 
and a function body. For the function header, you define the name of 
the function and the syntax of the function call. The function body 
consists of a series of statements and expressions that define the 
actions to be performed by the function when it is executed. 
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To enter function-definition mode, type a del character (V) followed 
by the function header and a carriage return/line feed. This signals 
the APL processor not to execute subsequent lines as you enter them, 
as it would in immediate mode. However, system commands are executed 
immediately. In function-definition mode, APL prompts you for suc- 
cessive lines of the function body by displaying successive bracketed 
line numbers for every line. All the lines you enter are treated as 
function lines until you type another del (V) . The second del returns 
you to immediate mode. Functions can have up to 1000 lines. 

The format of a function is shown in the following: 



[1] 
[2] 
[3] 
[4] 
[5] 
[6] 
[7] 
[8] 



V function header 



function body 



V 



There are no restrictions on the type of statements you can include in 
a function definition. You can include system commands in a function 
but you must precede them with the execute function. If you do not, 
APL executes them immediately. See Section 5.8. 

You can define and execute functions in quad input mode. The input 
request remains pending until you leave function-definition mode. 

You delete a function from your workspace with the system function UEX 
(Section 4.3.4) . 



6.2.1 The Function Header 



The function header contains the name of the function and the syntax 
of the function call. You type the function header on the same line 
as the del (V) that signals function-definition mode. There are six 
types of functions that you can define depending on the number of 
arguments the function header takes and whether or not the function 
returns an explicit result. Table 6-1 displays the formats of the six 
function types. 



Table 6-1 
Function Headers 



Type 




Explicit Result 




Type 


No 


Explicit Result 


niladic 


V 


variable -<-name 




niladic 


V 


name 


monadic 


V 


variable -^name arg 




monadic 


V 


name arg 


dyadic 


V 


variable -^arg2 name 


argl 


dyadic 


V 


arg2 name argl 



The arg, argl, and arg2 in the function header are dummy arguments. 
They look like variable names but they have no values assigned to 
them. A dummy argument is a placeholder for an actual argument 
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(value) you supply when you call the function. The number of dummy 
arguments in the function header determines the calling syntax of the 
function (niladic, monadic, dyadic). You must include the same dummy 
arguments in the function definition as in the function header. 

The variable in the function-header syntax (Table 6-1) is also another 
dummy argument. However, the presence of this variable in the func- 
tion header determines whether or not the function returns an explicit 
result. This variable temporarily stores the results of the function 
execution. You assign the function name to the variable in the func- 
tion header. If a function returns an explicit result, you can use 
this function in subsequent computations by including its name in an 
expression just as you would an APL function. A function that does 
not return an explicit result (no variable assigned in the function 
header), may also return a result when you execute it. However, you 
cannot use this function result for further work as a value within 
another function. 

Functions that return explicit results can be included as part of any 
expression. Functions that do not return explicit results must be 
either the only statement on the line or the last statement in a 
multi-statement line (last statement on the left) . 

The following function header returns an explicit result: 

Vf-^i-B r--Fi:OCv c 

In this function header, A is the variable (dummy argument) that 
designates this function to be one that returns an explicit result. 
The result of the execution is stored temporarily in A. The variable 
names B and C are dummy arguments, and PROG is the function name. 

When you call a function containing dummy arguments, you must supply 
the values for APL to use during execution. You include the values in 
the calling syntax of the function name. For example, if the function 
header has two dummy arguments: 

vA NAME x:< 

you must supply values for A and B. 
25 name: 42 

When APL executes the function, the values 2 5 and 4 2 are used in the 
calculations wherever you placed A and B in the function definition. 

You can also include local symbols in a function header. Local names 
must be unique from dummy names in the same function definition. See 
Section 6.2.2.1. 



6.2.2 Symbol Classification 

An APL workspace contains an area that is known as the symbol table. 
This area is empty in a clear workspace. Every time you create a 
variable name, function name, or group name (Section 5.4.4), this name 
is written, and referred to as a symbol, in the symbol table. (Dummy 
arguments are not recorded in the symbol table) . Any values you 
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assign to these symbols are also stored in the symbol table. When you 
save an active workspace, APL also saves the symbol table. 

Symbols are classified as being either local or global symbols de- 
pending on how their values are treated before and after function 
execution. The following subsections describe the characteristics of 
local and global symbols. 



6.2.2.1 Local Symbols - A local symbol has significance only during 
the execution of a particular function. To specify a symbol as being 
a local symbol, include that symbol in the function header and then 
assign it a value within the function definition. Separate local 
symbols from the function name with semicolons. All local symbols are 
placed to the right of the function name. For example: 



In this function header, I, LOC and G are local variables. Local 
variables have no significance in determining whether a function is 
niladic, monadic, or dyadic. Dummy variables do. See Section 6.2.1. 

During execution of a function, the local value is always dominant. 
For example, if a local variable has the same name in two separate 
functions, the execution of one function does not affect the value of 
the local variable in the other function. You initialize local vari- 
ables when you call the function, and any local values are lost upon 
exiting from the function. Using a local variable before you have 
assigned it a value results in an 11 VALUE ERROR. Note that there is 
no need to include local variables in the function call. 

Function-line labels (Section 6.4.2) are treated as local variables 
and are also initialized when you call the function; however, they 
cannot be assigned a value. 

System variables (Section 4.2) can also be localized within a function 
definition. 



6.2.2.2 Global Symbols - A global symbol has the same significance 
(value) throughout the scope of its workspace, whether or not it is 
inside or outside a function. You can change a global symbol, erase 
it, or expunge it throughout that scope. However, you can have only 
one global definition at a time for a symbolic name. 

Because naming conventions for functions and variables are the same, 
you cannot have a global function and a global variable with the same 
name. You can, however, have a local and a global with the same name. 
In this case, certain rules apply for determining which value takes 
precedence, global or local. See Section 6.2.2.3 for this explanation, 



6.2.2.3 Dynamic Localization - The phrase "dynamic localization" 
refers to the precedence of local symbols over global symbols with the 
same name. During function execution, the value of a local variable 
supersedes the value of a global variable with the same name. Also, 
depending on the particular function being executed, a local variable 
can supersede another local variable of the same name. 
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For example, if you have a global variable A and you execute a func- 
tion containing a local variable. A, APL uses the value of the local 
variable A during function execution. Once APL exits from the func- 
tion, A retains its global value. 

If two functions have a local variable with the same name, APL uses 
the value from the function in which it is currently executing. For 
example, the local variable B has a value of 10 in FUN CI and a value 
of 2 5 in FUNC2. While executing FUN CI, APL uses 10; while executing 
FUNC2/ API. uses 25. Upon APL's return to FUN CI, B resumes the value 
of 10. Finally, upon APL's exit from FUNCl, B has no value. 



6.2.3 Function Input and Output 

You can input and output data and the results of function execution by 
using the standard APL input/output functions described in Chapter 2. 
All the quad symbols (D) can be used in both immediate and function- 
definition mode. These are: 

1. Quad (D) or evaluated input. Section 2.5.1 

2. Quote-quad (H) or character input. Section 2.5.2 

3. Quad-del (0) or unedited input. Section 2.5.3 

4. File input (0), Section 7.2 

5. Normal output, expressed by simply typing a variable name. 
Section 2.5.4 

6. Mixed output, expressed by typing values separated by 
semicolons. Section 2.5.6 

7. Quad output (D) , Section 2.5.5 

8. Bare or character output (H or 0), Section 2.5.7 

9. File output (H) , Section 7.2 

File input and output are discussed in Chapter 7. The other varieties 
of input and output are described in detail in Section 2.5. 

One aspect of APL I/O, escaping from an input request within an 
infinite loop, is particularly relevant to a discussion of function 
execution. In this case, you may not be able to escape by typing the 
attention signal, two CTRL/Cs. You can escape by typing several 
right-arrows (->) . Also, you can escape from either quote-quad or 
quad-del input mode by typing the following: 

backspace U backspace T (or .OU from a non-APL terminal) 

Either form of escape has the same effect as function suspension 
(Section 6.4.3); it causes function execution to be interrupted but 
does not result in an exit from the function. 
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6.2.4 Comment Lines 

You can include comment lines anywhere in the APL function. They are 
particularly useful in annotating statements in the definition. 
Comments must appear on separate lines and cannot be included on lines 
containing APL statements. The first character in a comment line must 
be a lamp character (o), formed by overstr iking the down union (n) and 
the jot (°). APL treats the text following this symbol as a comment; 
and the text can consist of any combination of valid APL characters. 
Note that a comment cannot extend across line boundaries. 

When you display a function definition, APL begins a comment line one 
character position to the left of the rest of the text. Actually, the 
lamp character (fl) / itself, prints one position to the left. An ex- 
ample of this is shown in Section 6.2.5.3. 



6.2.5 Examples of Defined Functions 

This section contains three different examples of defined functions. 



6.2.5.1 Niladic Function - The following niladic function does not 



return an explicit result. Note the value of VECTOR, as a global 
variable outside the definition of AVG and as a local variable inside 

AVG. 

^AVGJ VKKCTOFi: 
II .til pif- ' HNTI-IIR THE VECTOP: TO BE AVERAGEXIi J ' 

i: 2 3 ' "If' H k: ^"•- 1^^ ^ ^J ' - ■'■ :•: "> ' y ( t- / V k;: c r o r ) •:• f y v i;:: <:^ t o r <•■ j: |^| 

[:3:i 

VECTORf- ' AXv<CX;i ' 
AVG 
ENTER THE VECTOR TO Bdi.' AVERAOEXi' ♦ 3 4 J^ ^, 7 

THE REiJSUUT .i: S 5 

VI:::CTOR 
ABCXIi 



6.2.5.2 Monadic Function - The following monadic function returns an 
explicit result: 

V A >•< S i- A V I:-: P: A (•> I:-: V HI! C^ 
LIJ ANSf. (.f./VEC).:.f s,VEC 

121 V 

AVERAGE 3 5 .4 6 7 



1. OCX AVERAGE 3 5 4 6 7 



soo 
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6.2.5.3 Dyadic Function - The following dyadic function included 



below does not return an explicit result: 
V L Ki: r T k: r x h s t f--. x n g o r 

i;- 1 ;j n ^"•' •■- "■ ^> l'^: '•' -> ^"^ ^-^ '^ •==• *"'■ •'• <^' '"■ '•> •■* •'• "^' •'• ^^^ ^"^ W l-l I:-; I-: I::! C H f^ R A C.^ T E. R 

II? J ft APPEARS .TN STFtXNCv 

r' 3 1 '' <■• < '- ^ "'' "'' "^"^ '''• "■■■ •=* '" •"• •"'• '■' ^ ) / U-' K "^ "■ '='•■ ■•• f •' t^' 

1:4;] ^0 9Ui"'l'i">5x \o-r"i' 

£ i:;j u • N O O C C U R fi-: N C B: S < 

Lir::TTERf. ' C ' 
Tf- ' GLOE'AL.. ' 

L. K:.- r r E R :i: f •< • a b <:' a c b c • 
3 5 7 

L. E r T E R I f-i ' L. M M D I-- ' 

NO QCCUREHCES 
.J. 

GI-OBAI... 



6.3 EDITING THE FUNCTION 



You can edit a function definition in a variety of ways. There is no 
need to go to a text editor outside of APL. APL has a line editor 
that allows you to add, delete, and change definition lines and also 
alter the function header. You can even edit individual characters in 
a line. See Section 6.3.7 for character-editing procedures. 

You must be in function-definition mode to edit a function. To open a 
function for editing, type: 

V function name 

After an addition, replacement, insertion, deletion, or display 
operation, APL displays a line number to allow you to add or enter 
additional text. If you do not want to do this, type a del (V) to 
close the function and thus shift from function definition to imme- 
diate mode. You can also type a del on an edit line. For example: 

K7 s r A r 
171 L'^^l"^' 



In this example, APL deletes line [5] and then exits from function- 
definition mode. The del can be included on any line except a com- 
ment line. 

After you return to immediate mode, the lines in the function are 
automatically renumbered sequentially, beginning at line ClH. 
Therefore, lines you insert with fractional numbers affect the 
function only while it is open for editing. 
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6.3.1 Adding Function Lines 

You can add lines to the end of a function in a very convenient man- 
ner. When you open an existing function, APL assumes that you want 
to add new lines and it displays the next available line number. For 
example, the function named STAT can exist in the following form be- 
fore you edit it to remove errors. 



Li;] 

1:3:1 
LAI 

L61 



VlSTANDXfHSUBvJ STAT M 
<5UM.Hf..f X 

i",umx2<-+/<'-^a2) 

fl t;: o M p u r ie m ki; a ?•< y v a h;: x a h c e. y s r (■> h jc f>\ \--: x.> i.< ki: v :i: o t x o h 

M IE <;;» H >'■. f ■ s y.i m >■■. :• h s u b j s 

M H C^ H X i- SUM )< -■ H S U B J 
V 



You can add lines in response to the bracketed line numbers displayed 
as shown below. 



17 
1: B 



K' S T A T 

flFUNCrxON RETURNS VAI...UI::: OF S T A N D A R p i:iE V X AT 3! ON OF 

s T A H J.! ;•? i- y A i-i: K n ^ ;-; 



To terminate the specification of additional lines, enter a del to 
transfer from function-definition mode to immediate mode. 



6,3.2 Replacing Function Lines 



You can replace existing lines in a function definition by entering 
function-definition mode, then specifying the affected line number and 
the new text of the line. In the next example, APL displays the line 
number [8] indicating that the existing function has seven lines. The 
first line of the function is replaced with the new text. 

VSTAT 



APL then displays the next line number after the replaced line, in 
this case, [2]. At this point, you can either enter new text for line 
[2], or escape from function-definition mode by typing V. 

The line number you specify must be a positive number less than 1000. 
If the line does not currently exist, it is inserted (see Section 
6,3.3). You can include a decimal point but you cannot specify more 
than three decimal places. 
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6.3.3 Inserting Function Lines 

You can insert new lines between existing lines of a function defin- 
ition by first entering function-definition mode. Then, specify the 
new line number followed by the text. For example, to insert a line 
between [5] and [6] you can specify any number from [5.001.1 to 
[5.999!]. To insert a line before line [1], you can use any number 
from [0.00 in through [0.999]. Note the following example: 

vsrar 

con 1^" *^^ ♦ '■' "I « •■* ''■' ^ ^" '- ^ ^^ '••• ^''- ^ "' *•' •"' '^^ '"• '■'• ^'^ '' ''' 
I- ♦ 6 ."J '•• S ♦ '^ "I '"' ^'^ •''• '■' ^" < ^^ '"' ^ ■"'■ -^ • ■•• ^^ ■■' '■' ^' "•' ^ ■•■ ^ ••■■■ ^'^ ''^ '"^ ^ 2 



The new lines are inserted between existing lines [0] and [1] and [5!] 
and [6] respectively. In each case, APL prompts with the next line 
number after the inserted line. To derive the line that is next in an 
inserted sequence, APL increments the present line number by 1E~D 
where D is the number of decimal places in that line number. The next 
line after [0.5] is thus [0.6], the next line after [5.5] is [5.6], 
and the next line after [8.29] would be [8.3]. Line number [6] is 
after [5.9], and line number [7], not [6.1], is after [6]. You can 
enter new text for the line number displayed, override the line number 
by specifying another one, or return to immediate mode by typing a V. 

After you close the function, APL renumbers the lines to consecutive 
integers beginning with [1]. Line numbers you insert must be positive 
numbers up to but not including 1000, with or without a decimal point, 
and with no more than three decimal places. The renumbered function 
definition now exists in the following form. 

S? STANDKfNSUBU STAT X 
I" I -I flSUM ELEMENTS OF ARRAY K 

|"p"j SUMX<...f/X 

II 3 1 ••' ■•' ^ ■'' 2 *■■■ ■*■ / ( ''< A 2 ) 

|- /^ "I rt c o M I"- u T 11." M i-i: A ti f, s-* A I-: :i: a i( c i;:: « s t a n x:' a i=i: v x:< b. v :i: a t :i: o ii 

I" nij "I M !•;: (>i )■( X i- S U M X ■:■ N S U B ..) S 

|- ^^ "I M E fA N X i- S U M X ■:• N S U B ^.) 

J- -;, "j V fA R X i- ( S U M X 2 ■••■ >■( S tJ Xvt >J ) •••■ M Hi: f>t N X A 2 

\"Q"l f^FUHCrXQN RKi: TURNS VALUE OF STANX.iARD DE V ."i: AT X ON OF X 

I" 9 •I s r A ii x:' x «.. v a k ;c a o <. S 



6.3.4 Deleting Function Lines 

To delete existing lines in a function-definition mode, you type a 
delta (A) and the line number both within square brackets. For 
example, to delete line [5] of STAT, type the following: 

VSTAT 

i:ioj c-^s::! 

L'5"J '^' 
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APL displays the number of the line just deleted to give you the 
opportunity to type a new version of the deleted line. You can enter 
new text or escape from function-definition mode by typing V. After 
you close the function, APL renumbers the lines. 



6.3.5 Displaying Function Lines 

APL gives you the ability to display an individual line, a part of the 
function definition from the specified line to the end, or the entire 
function definition. 

To display an individual line, type the line number and a quad char- 
acter (D) within square brackets. For example, to display line [3] 
of function STAT, type: 

v?sTAT[:3o:;i 

1:3:] V 



APL prints the number of the line just displayed to give you the 
opportunity to specify a new version of the line. You can now perform 
any editing operation or escape from function-definition mode by 
typing V . 

To display the function definition from a particular line number to 
the end, you type the quad character first and then the line number 
from which lines are to be displayed. For example: 

vsTATi::a7j 

\Z71 flFUNeT:i:o?< ke turns value of stanjcarx:' i:iev:i;at:i:ow of ;< 

|- y 2 ^••> T' <'^ '■' Jt.' y- <.. V A F: ;■( ft , 5 



APL displays the number of the next line after the final line of the 
function definition, in this case [9], to give you the opportunity to 
add more text. 

To display the entire function definition, type the quad character 
without a line number. For example: 

VSTAT|"n;:|-7 
V STAra:iX<. HSUB.J STAT X 
mil flSUM EI...EMEHTS OF ARRAY X 

i:2::i suM.xf..}./x 

1; 4 J n <" o M I"- 1 J r i::-: m ii." (■'h \\ y v c;* r i (■■>, \\ c ii-: y s t (> \\ x:i a i-: xh x:i i-i: v x a t x o w 

II 5 "1 M III: A H >i <•■ » U M H .:;. H S U X-f J 

II 6 II '^'^^■^' '•' <•• ( •••> I' M >' 2 ■■:•■ '•< "> ' ••' » >.^ ) ■■•• M III: (^ ii x a 2 

11711 ftFUNCT-lOH returns VALUE OF STANX-iARD X;i E V .X A T .t O N OF X 

II 8 .] S T A H X:> X <•■ V A Hi: X ft () , '5 
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The V characters preceding line Cl] and following line [8] indicate 
the delimiters of the function and identify its name. They do not 
change the mode as the function prints. APL displays the number of 
the next line after the final line of the function to give you the 
opportunity to add new text. 

If you want to display a line or an entire function and return to 
immediate mode after the display, type the closing V on the same line 
as the display request. For example: 



6.3.6 Editing the Function Header 

You can edit the name or arguments of a function header by accessing 
line number [0]. You can display and replace the function header just 
like any other line in the function. However, you cannot delete the 
header using the delta character A. Also, you must include a valid 
function header before leaving function-definition mode. 

The following example displays the function header: 

VSTAT 

c?:.! i::oo:] 

V7 STAHDKfHSUBJ STAT X 

\:oi ^ 



Notice that the header is displayed without a line number. When you 
specify a character position in the header (see Section 6.3.7), APL 
types the header with line number CO] and without the V. For example 

V<r> TAT 

1:9;] tOUVl 

to:] STANDX<-H%UBJ STAT X 
A 



The caret in the above example indicates the position of the terminal 
head. It does not print on your terminal. Line-editing positions are 
discussed in Section 6.3.7. 



6.3.7 Character-Editing Procedures 



Besides providing a way to edit a function definition line by line, 
APL allows you to edit a function definition character by character. 
Character editing is a multiple-step process. The first step involves 
deleting characters no longer needed and inserting blanks in the line 
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to allow additional desired text to be typed. The second step in- 
volves typing in the new text. Repetition of these steps is often 
necessary. The final appearance of the line should be identical to a 
function line just entered from the keyboard. 

To modify a line, specify (1) the line number followed by (2) a quad 
character (D) followed by (3) the estimated character position at 
which editing is to begin. 

For example: 

£71 i:::li::i;i.o::i 

[■ i 2 AfRAGAMMA ■J. 

A 



APL displays the line, performs a carriage return/line feed, and then 
positions the cursor or terminal head at the position you specified. 
In the example above, the caret (A) indicates the position specified; 
it does not print on the terminal. If you specify position 0, APL 
places you at the end of the line. Once you are in the desired posi- 
tion, you can do any of the following: 

1. Delete a character by typing a slash (/) beneath each 
character you want to delete. 

2. Insert a space by typing a digit or letter beneath each 
character before which you want to insert a space. Typing 
the digit 1 beneath a character inserts one space before that 
character. A 2 inserts two spaces, and so forth. You can 
insert multiples of five spaces by using letters. Typing an 
A inserts five spaces; typing a B inserts ten spaces and so 
forth. If the number of spaces you specify plus the current 
line length exceeds the length of the terminal line (the 
value of UPW) you will receive a 5 DEFN ERROR error message. 

All other characters you type are ignored. 

When you press the RETURN key after inserting spaces and deleting 
characters, APL displays the line with the inserted spaces and without 
the deleted characters. It then performs a carriage return and 
positions you at the first inserted space on the line to be edited. 
If you did not insert spaces, APL positions you at the end of the 
line. You can enter new text in the spaces or make further modifi- 
cations to the existing text. On APL terminals, you can backspace 
to insert new characters and can create illegal overstrikes to aid 
in retyping the line. 

If you change the line number while you are editing the line, any 
edits you make correspond to the new line number. The original line 
remains unchanged. 
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The following example illustrates the use of character-editing in 
correcting the line: 

II :l 1 "" *! • ( '••• ■=•• '^' "^ '^'- "- '•=' '^' ^''' ^- '■* '■' / ^ B ••"■ y "> "I' ••■': •'•■ f-< <>' 



There are several errors in this line: 

1. LETTER is misspelled LETTR. 

2. The right parenthesis is missing after STRING. 

3. The "8" should not appear at all. 

4. The "P" should be p. 

Because the first error occurs in LETTR, you could edit the line this 
way: 

VFUNC 

irsj i::ioi4:i 

1 1 1 r i- ( L E r r r ■„■■.: s r r x h g / \ 9 i==- y b r r x n g 

1 1 / / 

C 1 3 T<~ ( L.ETTE:R=:STI=i: X MG ) / ^ T y STK X HG 

1:2:3 ^ 



The cursor or terminal head is now positioned at the space between T 
and R. You can now enter the new characters, spacing over the text 
you want to preserve. To do so, type the following: 

1. £" in the space between LETT and R 

2 . ) in the space between STRING and / 

3 . p in the space between x and , 
The new line looks like this: 

vFUHCi;::ir:i::iv 

1: :L :\ V- i- ( l„ lii: T T- E I'l: :::: S T R X iHi ) / \ f> y S T R X H G 

When you press the RETURN key, this line replaces the existing func- 
tion line [1] in your function definition. 

You can type a deliberate character error, for example, an illegal 
overstrike, after a character-editing display to cancel the revision 
of the function line. When APL encounters a character error, it 
displays both an error message and the line up to the point at which 
the error occurred. However, you cannot escape from character-editing 
mode except by completing the line. 
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6.3.8 Performing Immediate-Mode Editing 

You can edit lines during immediate mode as well as function-definition 
mode. In immediate mode, line edits affect the last immediate line 
entered from the keyboard. Because immediate-mode lines do not have 
line numbers, type (1) any arbitrary legal line number (that is a num- 
ber less than 1000) followed by (2) a quad character ([]) followed by 
(3) the character position at which editing is to begin. For example: 

A C: R O H f . I N I T J „ I W X T 2 i '^' ?' 'i- T' 3 
7 SYNTAX ERR OP: 

A c R o w <- 1 w 1 T 1 y I H .T T 2 [; X N :i: r- 3 

A 

Cia233 

ACRQNf. XNXriyXNX T2 1: X H XT^ 

/I 
ACROWf 1 N I T 1 J, .T N X T2 » 1 H X T3 



Immediate-mode editing proceeds exactly as in function-definition 
mode. However, after you press RETURN to conclude the final edits, 
APL executes the line. Note that the DELETE key (RUBOUT) , CTRL/U, 
and CTRL/R also work in immediate mode. 



6.4 EXECUTING THE FUNCTION 



The process of defining a function associates the function header 
provided by you with the statements you enter as the function body. 
When you decide to execute the function, you use the function name as 
you would use a primitive APL function. The information provided in 
the function header specifies the number of arguments to be supplied 
in the function call and determines whether or not a value will be 
returned. Section 6.2.5 provides examples of defined functions and 
their corresponding function calls. 

It is also possible to issue function calls from within other func- 
tions. You can nest functions to any depth. 

The following sections provide information on function execution. 
They focus on branching, suspending, tracing, stopping, and locking 
functions, using the state indicator, and trapping errors. 



6.4.1 Branching Within a Function 

APL statements in a function definition normally execute in the order 
determined by their line numbers. Execution begins at the first 
statement following the function header, terminates after the last 
statement in the definition, and executes only once. You can modify 
this standard order of execution by including branch statements in the 
function definition. A branch statement changes the sequence of exe- 
cution by transferring control to another line in the function defin- 
ition. Branching allows you to execute loops within the body of the 
function. 
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There are two types of branch statements: unconditional and condi- 
tional. An unconditional branch statement consists of a branch symbol 
(^) , followed by the number of the function line or label to which 
you want to transfer control. For example: 

Z'51 ■>! 



This statement causes an unconditional branch from line [5] to line 
[1]. Line [1] is thus the next statement to execute. 

The line number you specify after the -> can be in the form of a con- 
stant, a variable, or an expression. It must be equivalent to an 
integer line number within the current function definition to allow 
execution to continue. If the integer does not reference a line num- 
ber in the current function, the branch statement closes the function 
and returns you to immediate mode or to the caller. (APL users often 
deliberately specify an out-of-range number to stop execution.) Line 
number CO], the function header, is not a legitimate reference for a 
branch statement. Therefore, specifying ^0 also closes the function 
and returns you to immediate mode or to the caller. 

If the object of the branch is a nonempty vector, control passes to 
the line number referenced by the first element of the vector. If the 
vector is empty, the branch statement is not meaningful and the normal 
order of execution continues. 

You can include a branch statement in the middle of a multi-statement 
line. However, if the branch executes, the rest of the expression to 
the left of it is ignored. If the branch does not execute, the result 
of the statement scanned so far is considered the empty vector. There- 
fore, the expression to the left of the branch is executed. 

APL also allows you to include conditional branches in a function 
definition. A conditional branch executes as the result of evaluating 
a logical expression, not in response to any specific IF logic. There 
are two popular ways of doing a conditional branch. The first format 
is: 

-^ line number x logical expression 

For example : 

••>9xx >B 



APL evaluates the logical expression to the right of the line number 
specification (^9) . Logical expressions return either a 1 (true) or a 
(false) . Therefore, if I is greater than B, the value of the ex- 
pression is 9x1 and control passes to line number [9]. In the ex- 
pression ->(^<B)/13, if the logical expression A<B evaluates to 1, 
(1/13), then control passes to line number Cl3]. (If the logical 
expression evaluates to 0, (0/13) returns a null so control passes to 
the next line. ) 
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You can include more than one line number in a conditional branch but 
each line number must have a corresponding logical expression. Only 
one expression can evaluate to 1. Both the line numbers and the ex- 
pressions are separated by commas. For example: 

•X ( A > B ) ^ ( A < B ) , A:.::B ) /7 y 8 y 9 



APL transfers control to the line number whose expression evaluates to 

1. 

Note that you should use labels instead of line numbers in branch 
statements because APL renumbers when lines are added or deleted. See 
Section 6.4.2 for a description of labels. 



6.4.2 Statement Labels 



Because APL automatically renumbers function lines as consecutive 
integers when exiting from function-definition mode, problems can 
occur when you refer to explicit line numbers in branch statements. 
Instead, you can associate a line number with a label and reference 
the label, not the line number, as the object of the branch. For 
example: 

[15] INCR: J->J+1 



[27] ^ INCRxI<IMAX 

As shown above, a statement label consists of a distinct identifier, 
followed by a colon (:) . When you specify the label in the branch 
statement, you do not include the colon. The internal value of the 
label identifier is the line number with which it is associated. 

A label acts like a local variable in that its value is local to the 
function in which it appears. Label values are internally respecified 
upon each exit from function-definition mode. You cannot explicitly 
define a value for a statement label, and you cannot place a statement 
label in the function header. 
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Following are two examples of defined functions that use branching and 
statement-labeling techniques. Note that APL prints lines containing 
labels or comments one character to the left of the rest of the text. 







VFACTORXAL.|:03V 




s? 


RfFACTORIAL M 


i:i3 




•==:<-! 


C23 




•>OxiO™^' 


1:3:3 




Rf-RXN 
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->2 
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K7FAC|:0JV 




V 


Z<S-FAC i( 


t: .1. ::i 




■.)irZE-:ROX\li:~0 



II2:J ZfNxFAC H-l 

II' 3 :J ft i^'^ C) T X C E T I ■) A y Pi: B C U R 1l> X V E K' III: l=" 31 N X T X O tl S 

11 4 .'.I ft f^ f'- '•" •'"■ K' Hi: M X T ni: x:i 

i:s::i -^o 

1:6:] hzki:rojz<..i 

FAC 5 

:l.20 



6.4.3 Suspending Function Execution 

Function execution can be suspended before normal completion by means 
of: 

1. An error report 

2. An attention signal, two CTRL/Cs 

3. The stop control vector 

4. The BBREAK system function 

When an error occurs, APL suspends function execution and displays an 
error message and the line number where the error occurred. Appendix 
A lists possible errors you may encounter. The attention signal, two 
CTRL/Cs, is described in Section 1.4.4. The stop vector is described 
in Section 6.4.6. The UBREAK system function is discussed in Section 
4.3.1. 

When function execution is suspended, APL displays the name of the 
suspended function and the line number of the statement that would 
have been executed next. APL then begins a new line, indents six 
spaces, and awaits input in immediate mode. You can perform any 
operation at this time, including erasing the suspended function (see 
the ) ERASE system command. Section 5.4.2). 

The suspended function remains active until you terminate it, erase 
it, or clear the currently active workspace. You can resume execution 
at any time by typing: 

->■ line 
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where line identifies the line number at which execution is to be 
continued. You can terminate a suspended function by typing: 

->-0 or just -*■ 

When a function is suspended, its local variables remain active. You 

can examine these variables and can specify their values by using an 
immediate-mode assignment. 

DLC contains the line number of the line where execution was sus- 
pended. Therefore, -^ULC restarts the suspended function at the 
beginning of the line that was interrupted. 



6.4.4 Examining the State Indicator 



The state indicator is a status vector that resides in your active 
workspace. You can examine the state indicator to determine the 
status of all active functions by specifying an )SI system command 
(Section 5.4.8). The )SI system command lists active functions as in 
the following example: 







)SX 


T| 

5| 


::3::i 
[7::i 


ft 


K 


i:: 6 ::i 




f--\ 


i::2::i 


ft 



The listing displays functions in the order in which they were most 
recently active. The example included above indicates that execution 
was suspended during execution of statement [3] of function T, which 
was called during line [7] of function S, which was called during line 
[6] of function R. (Before this sequence of calls, execution was 
suspended during execution of line [2] of function F.) 

In the )SI display, an asterisk (*) following the name and line number 
indicates a suspended function. The other functions in the list are 
pendent. A pendent function is one which is awaiting return from 
another function - possibly a suspended one - which it called. You 
can edit a suspended function but not a pendent one. Although you can 
erase both suspended and pendent functions, you can cause considerable 
confusion by erasing a pendent function and then resuming execution of 
a suspended function that was called by that pendent function. Fol- 
lowing is an example of an operation of this kind: 

)SX 

»i::4:3 



<-i::i5J 



ft 

B 1:4:1 



)r£RA1:>E:: A 

)s:i: 
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You can resume execution of C at this point but not B. In the )SI 
display, an asterisk without a line number indicates an erased 
suspended function. Whenever you erase a pendent function, APL 
displays: 

13 poss:i:bi...h s:i: x:iamage 



to warn you to consider the status of existing functions before you 
resume execution. 

From the )SI listing you can also determine when quad-input requests 
are pending or an execute operation (e, i, , or ±) has been invoked. 
Local functions (suspended or pendent) also appear in the )<S'J listing, 
An example of both of these special conditions is shown below: 

) s :i: 

'=i;:2:;i * 
Ai;:7;;i 



Tfi::i 

;: ' \ <:> X. ' 



at 



'"r:2::i 
«i;:7;:i 



You can clear the state indicator by terminating the execution of each 
suspended function in the list. There are several ways to accomplish 
this: 

1. You can type a right arrow (->) for each function marked by an 
asterisk. 

2. You can issue the I-beam function i3 to clear the state 
indicator completely (Appendix C) . 

3. You can clear the state indicator by saving the active 
workspace, then clearing and copying it again (see the )COPY 
system command. Section 5.4.1). 

If the state indicator is clear, APL outputs a blank line in response 
to )SI. 

You can use the )SIV system command (Section 5.4.9) to obtain a more 
extensive display of the state indicator. In addition to the infor- 
mation accessible to )SI, )SIV returns a list of local and dummy 
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variables for each function displayed. The current line being exe- 
cuted by the execute function is also displayed. The following is 
an example of an )SIV display; 





)SXV 






si:63 


A 


L.I 




•=■1:23 


* 


•f 




Ai:7n 




7' 




T[:3:i 










•r?Zt-P\ M 


Bjn:i:Oy« 




111 


|:]»|:;:il::ai< 


•UCNE I OF 


M " 


\:2i 


1 M 2 






LINE 


1 OF M 

) s :i: V 






MCI.! 


ft 


'Z 


« 


"^111 


K. 


V 


IJ 



a:i:o 



This indicates that the variable T, local to function F is currently 
dominant, and that the variable T local to function A, as well as the 
function named T, are currently inaccessible. 



6.4.5 The Trace Vector 



You may find it helpful for debugging purposes to obtain an automatic 
printout of intermediate results of function execution. As a program 
tracing aid, you can output the values computed by one or more func- 
tion statements each time those statements execute. 

To set the trace vector, use the following format: 
TA function name-^-line number (s) 

where function name is the name of the function you want to trace and 
the line number (s) are the lines you want information on. 

You can set the trace vector in either immediate mode or within a 
function definition. For each execution of the line numbers you 
specify, the trace vector causes the following information to be 
displayed in the order shown: 

function name 

bracketed statement line number 

final value returned by each statement on the line 
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An example of a trace operation is shown below: 
TAr"f-4 6 7 

i^i::4::i 32 «5 37*9 
i=n:6::i 9 



If the statement being traced is a branch statement, then the value 
printed is the line number to which control is passed by the branch. 
In the example above, line [6] was ^9. 

To trace all the statements of a function, for example F, you can 
supply the following specification: 

where N is a number at least as large as the number of statements in 

F. 

To disable the trace vector, type the following: 

Tl^FUNCTION NAME^iO 
For example: 

T,;M"j.. \ 

The trace control vector can be set within a function to aid in 
selective tracing or setting breakpoints. For example, you may want 
to initiate tracing if certain conditions are in effect and disable it 
as soon as a specified value has exceeded a defined maximum. 

If you edit a function for which you have defined a trace control 
vector, you clear the trace vector. Also, when you lock a function, 
you automatically clear the trace vector. The trace vector setting is 
saved with your workspace. 

Note that APL identifiers cannot start with TA because this is re- 
served for the trace vector syntax. 
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6.4.6 The Stop Vector 

APL allows you to suspend execution of a function at predetermined 
points. A stop control vector is available with a syntax similar to 
that of the trace vector. To cause statement execution to stop before 
executing a particular line, you can type the following: 

S'Afunction name-<-line number (s) 

where function name is the name of the function you want to suspend 
and line number (s) specify where you want to suspend execution. You 
can set the stop vector either in immediate mode or within a function 
definition. When you execute the function, the stop vector suspends 
execution at the first line number you specify. It displays the 
function name and the line number. You can resume execution by typing 
a branch to the desired line number (->5) or continue by typing ->D£C. 
The stop vector will then suspend execution at the next line you 
specified. 

When you edit a function for which you have defined a stop control 
vector, you automatically clear the stop vector. Also, when you lock 
a function, you automatically clear the stop vector. The stop vector 
setting is saved with your workspace. 

Note that APL identifiers cannot start with ^A because this is re- 
served for the stop vector syntax. 



6.4.7 Locking a Function 

APL allows you to lock a function definition to protect it from 
unauthorized use, to maintain security, or to treat a function as a 
proprietary program. To create a locked function, or to lock an 
existing function, you open or close the function with a del-tilde 
(¥) character (protected del) rather than a simple del (V) . The 
del-tilde (V) is created by overstriking (V) and (~) . 

The following example illustrates the locking of a previously unlocked 
function definition: 

«;/tr:i:g 

i:: :i. 9 ::i ^ 



A locked function cannot be edited in any way; if you try to edit a 
locked function, you will receive the error message, 5 DEFI^ ERROR. 
You cannot add, change, delete, or display a function line. Trace and 
stop vectors cannot be defined or changed for the function. Any trace 
or stop settings in effect at the time you lock the function are 
automatically cleared. 

If an error occurs during execution of a locked function, the function 
name and line number at which the error occurred are displayed, but 
the contents of the line are not displayed. APL then causes an exit 
from all pendent functions that are locked until the function on the 
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top of the SI stack is not locked. If all functions on the SI stack 

are locked, APL clears the SI stack and enters iiranediate mode. Note 

that you cannot unlock a function once it is locked. However, you can 
delete a locked function by using ) ERASE. 

CAUTION 

If a locked function calls an unlocked 
function and the unlocked function 
becomes suspended, the environment of 
the locked function is available for 
examination. 



6 . 5 ERR'dR TRAPPING ""' '-' • ^/^ .<.-=•■=■. -"'-'■ '■,^. 

APL provides a form of error trapping that allows you to handle errors 
from within a user-defined function. With error-trapping aids you can 
handle a failure that occurs within a user-defined function in the 
same way as an APL primitive function handles a failure, that is, by 
informing its caller that it failed and why. 

Normally, if APL detects errors while executing a function, it sus- 
pends execution and prints the error information on the terminal. 
However, if you plan ahead you can prepare alternatives that can save 
you time in the event of an error. What you need is the ability to 
gain control once an error occurs. You need to know what the error 
was and where it occurred, that is, the function name and line number 
of the statement that failed along with an indication of where the 
error occurred in the line. It woiild also be useful if you could halt 
execution of a function, check the flow of logic, then reenter the 
function and resume execution. 

The following system variables and system function, whether used 
together or separately, give you the tools to create your own error 
handling routines: 

1. UBREAK system function. Section 4.3.1 

2. UEEROR system variable. Section 4.2.9 

3. US ZONAL system function. Section 4,3.10 

4. UTRAP system variable. Section 4.2.21 



6,5.1 Considerations for Error Handling 



There are certain questions you should answer before you begin to 
define error routines. These questions are: 

1. What error do you want to trap? 

2. Where (in what function (stack level)) do you want to handle 
the error? 

3. What errors do you want someone else to handle? {QSTGNAL to 
caller) 
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4. When do you hit the panic button and which panic button do 
you hit? iDBREAK to immediate mode or let APL have it.) 

5. Where do you go after you fix your mistake? 

Taking these questions into consideration before you define a function 
can help you optimize your error trapping. 

Section 6.5.2 contains an example of how to handle one error trapping 
situation. 



6.5.2 Error Trapping Examples 

The first example sets a trap to handle the occurrence of an index 
origin set to 0. If an error occurs during function execution, APL ± 
executes DTEAP which, in this case, is set to go to label IQ . At 
label 10, APL checks to see if UIO is equal to 0. If UIO is 0, APL 
proceeds to label SET, where UIO is reset to 1. Execution then pro- 
ceeds to label DIV, where APL executes the expression again, this 
time with ZIIQ set to i . 

V ;; <!•■ f^ V ;i: v :r v b b ; \"\ r r-: f> f- 
II :!. :] n "^ '"' ■'■ ■■> '"' '•' '■' ^- '^' -^ ^-^ " '^' '^ '^ '■■■■■' ^^ '■' *■' M B E P: y A j, ft it ti 

II 3 1 n '- ■■■' ^-^ ^ '"■ '■•• '■■• J 2 ^' ■'■ V 3: i:' li-: 3 w :i; 1... 1... 1-: iii: 'T' u i^;: ?i 

II ■^:i nl^^ 3 •■ll::i...li::Mli::H7' V lire TOR 

IIJ5II ft"'"' 2-^rl, 2v-2>- 2v-3» 

11611 OTRArM" ' ■>.r.o < 

i;;7;:i ic :i; v j z ,■■ A •:. n » 

II 8 n K) 

L9II ioj..><0"::|I|:i:o)/si:::t 

III 1 III ^' '■'■ '"■ ^-^ ^ ' ''■' ■'■ ''■'' ^- "■' '■■• '■■■ ''■• •''■ <•' •''■ ' 

lil:l.:j ii>i;::T;i;:|:i;o <..;!. 
11:1.211 ■M-':iv 

i;:i:i:o{..o 

25 riii: v:i:i:"i::: 'f, 

25 :l.2»5 8.333333333 A » 25 5 

giiilRROft 

x;i :i; v :i: d ii:: i;; 7 ;;i i> :i: v ; z i- f> ■:■ \ b 

A 

) s :i: 
III -i- '■■> 



Notice that APL executed the function even though UIO is set to 0. 
UERnGR contains the error that occurred, but the trap handled the 
situation. UIO is now set to 1. 
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The State of DIO is the only check point in this function. If another 
error occurs, the function suspends execution and breaks to the termi- 
nal because of UBEEAK. 

KaVXDK: ERROR 
Qfil'RROR 
1 S I'l O M A 3: ii B R R O R 

» .'£ V I ri e: j" 7 :;| 1:1 :i: v j z i- a ■•-■ % » 

A 

o3:v.Tt.E:|;;io:3 '* 



UBEEAK prints the argument you supplied and suspends execution. 
UBREAK does not set UERROR but 3SIGNAL does. 

The next example works with three functions: MASTER, ERROR, and 
SNIGGLE. MASTER takes a right argument of either a scalar or a 
vector. It adds 'JO to each element and then passes the vector to 
SNIGGLE, SNIGGLE tries to turn the vector into a square matrix. If 
the matrix cannot be squared (does not have an integer square root) 
SNIGGLE signals a user-defined error '55 NOT SQUARE' and pops back to 
MASTER, MASTER has a trap set to send errors to the function ERROR. 
Here are the functions; 

vMAii: ri:::p|:o:]v 

V :zi M A s r 1:1: 1=:: V 1:1: c r a n-. p i::i v i-: a i-- 

1 1 ^1 "'' ^'''- ^^ '"■ <■■ ' '•■• '"• '''• *•* ''*• ' 

i:.21 flPEI!::r< MASTER A VECTOR y Atif" SO TO lil.ACH El-EMENT 

\:z:i flA»a:' RASis .TT TO <i>h:i:(:vCvi...e to maki-i: :rr souare: 
|- 4 ::i Si hi :i: G G I... B V lit: c t o r •♦■ 5 

iV'yi fl^-'" '^"^ Ri:!:FUS>l:iMS TO GlillT SOUARE „ BEHii XT TO JiilRROR 

1:6:1 Zi-MfrTRXX 

\? 

^i:,H:roGL..i:!:|.;j;;i;3v 

V !■; f- ! X <:■> cv I... 1;=; V B. c ; p t I't c^ i-- 

1:1 3 flTn:i:s PROGRAM TURHS thk: vector :i.hto a iiXsuARNi: matr:i.;-i 

1:2:1 fl :'•'"■ T" '•'":■•' VII::CTOR WON'T GOy SIGNAL. UP TO THIli: C Al...l...lii:R ^ 

i;ij:i rj 'If' •'■^ ''>'"■<••' ^ SWIG' 

i::4;3 matr:i:>{<-( ( (fVE:c)A0,5) y <f vii-C) ftO,s)/>VEC 

1:5 J -X) 

1: 6 3 •■■' ^"^ ■'• '•' t ' '■' ^■' "'^ "' *■* ^■' "^ '"■ •=•■ ' l-'l '■> •'• *•' ^'^ '^ '■■• '3 1^ 

v^:;l=■:R()R|;:i..|:;|^;? 

V i^J-hiiRROR J A 

1: 1 :i ■> ( 550;^i:iP :k 3tC]ii::i-:Rori: ) /i;;: iii: i< 

1:3:1 •^Oi'*"<■MA<r^Tl:::R v(i(:cTOR^i..vi:i:cTORy ( <A)it2) rviiiiCTORjfO 

i: 4 :i e fc"; K J R B A i< ' u H o H ' 
V 
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The following function executes MASTER. 
The sequence of events is as follows: 

1. MASTER is called with a vector that is not square, \B. 

2. MASTER initializes the localized LTRAP. 

3. MASTER calls SNIGGLE with the argument i8+5 0. 

4. SNIGGLE initialized its localized UTRAP . 

5. At SNIGGlElh:\, the expression causes a 15 DOMAIN ERROR, 
thereby invoking the error trap. 

6. UTRAP is equal to ^^SNIG^ so i UTRAP redirects execution to 
line [5l. 

7. At this point, UERROR contains the 15 D0>:AH: ERROR. 

8. At line 162 »Si^IGGLE uses USI3NAL to set DERRCR to the user- 
defined error message. 

9. USI"NAL terminates execution of SNIGGLE and forces an error 
at MASrERLi^ \ , where J!;'IGGLE was called. 

10. At MASTERli^^, error trapping is invoked. (Note that MASTER 
is on top of the )SI stack now.) 

11. UTRAP is equal to ^ERROR\ so i UTRAP executes the function 
ERROR, (Note that ULC at this moment is line [U], where the 
error occurred.) 

12. The function ERROR checks to see if UERROR contains error 
number 5 50. If it does not, ERROR breaks to the terminal for 
assistance. 

13. The function PRROR corrects error 550 by extending the argu- 
ment T.ICTOR with enough zeroes to make it square. (Note 
that VECTOR and Z in ERRORll^ are local to the first call to 
MASTER .) 

14. MASTER is called with the vector i 2 3 ii 5 6 7 8 'J , which 
sets the global matrix to: 

51 5 2 5 3 

b M- 5 ') 5 6 
5 7 5 b '3 9 

then returns to the function ERROR* 
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,X5 v-4:S* ;^; The function ERROR ret.Hrm|^..itpj-.i UTRAP at MASTERl 



^J. 



16. The trap expression does not cause control transfer and is 

complete. Therefore, APL breaks to the terminal with the )SI 

equal to MAF.TER [ M ] * . 

MftliTli-IP: \B 
51 S2 53 
54 55 56 
57 58 50 

M (^ s y e: i-.- 1;; 4 ;:i s w .1: (s <:» 1... e: v k: c t o r •». '5 



) s X 



Note that the error is signalled in MASTER not SNIGGLE. 

The next execution of MASTER causes a break to the terminal: 

MASTKIFt ' A»C ' 
UH OH 

:l. 'J x:ioma:i:m etirop: 
M A i» T is: 1=;; j;; ^ ;i <if h ;i: o (.•; 1... 11:: v ii-: c^ v o f-: i «■; 

A 

liLRRaRi;:^;;! a 
.f. 

MA=iri:.=.R[:4::i a 



The following functions cause surprising results when executed 

i:;:5::i -k) 

1 4 "I • M A r 1=:: :i; ; ^ :i: ?j v li." Pt <■.> :i: o ?•< 1:1: pi: 1=:: o p: , i^nr ¥■: :i: ;•; w a is ♦ 

i::5;:i a 

i::6:i oerrdr 

vgi:;i:j;.|v 

V Zi-Ci A 

i::i:i ^^m:;ia 
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Note the following sequence of events: 

fl<-2 2r 1^20 i^'^'ao 

„„r.-./«vE,.s«H ERROR, «««^« »">'"• 
J.000000000«=20 0_„^„<,oooOOE-20 
.,-| vAuuis; e:F:F;:OP-. 



1" A 



[;ifii;P:P:OP: 
J j^ V A i. (-'•••: pnP-.ROP: 

,■•:• A 



)SX 



,,,. iB What happened: ^^^ ^^^^^^^^^ ^^^^^ 

1. FCl?. sets Ori?AP to go to line l ^ -i / 

is reported. 
2 n2^ calls <7 with the singular matrix A. 

. . , domain error which invokes error trapping. 
T GCn gets a aomain txiv^^ 

.to the global value '->h', so at line M, 
4 nr/?AP is now set to the giood 
' APL does 1 UTRAP. _ 

. 1- V 4-^ rf'^l. without 
TL-i in G so (^ exits back to iL-.l/ 
5. There is no line t^;^ 1^^^° 
setting a return value for Z. 

6 APL reports the err:-- 

.„a inloKes error trapping which again aoes . omP and goes 
to line [4l. 

.he value of .U and an unexpected UEBROE are 

7. The message, the value ot , 
printed. 

^« its return value Z. Therefore, APL 

8. F exits but never sets its retur 
complains with 

•11 VALUE ERRQF. 
F A 



A 



...ion -4' in F had surprising consequences 
The specific error expression 4 
when executed in G. 
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CHAPTER 7 
THE FILE SYSTEM 



7.1 INTRODUCTION 

The file system is an integral part of the APLSF language itself. It 
allows you to store data files on a number of system devices. 

APL can create and handle a variety of file types. You determine the 
size and content of the records and the structure and access proper- 
ties of the file. You can write records into a file in either immedi- 
ate mode or function-execution mode and subsequently retrieve them. 
One of the most significant extensions of this implementation of APL 
is the inclusion of a powerful data-file capability. 

APL allows you to create and store four types of files: 

1. ASCII sequential 

2. Internal sequential 

3. Direct access 

4. Binary access 

ASCII sequential files allow you to create and/or read any standard 
ASCII file while at APL level. You can read and work with an ASCII 
file created by another language, or you can create an ASCII sequen- 
tial file to be passed to a program in another language such as 
FORTRAN or COBOL. Internal sequential files and direct-access files 
can be created and read only by APL functions (or by you in immediate 
mode) . Binary-access files can be accessed in any format as random- 
access memory, and can be read and written in almost any language. 

The file system has three distinct components: 

1. File functions that allow you to read from a file (0) and 
write to a file (S) 

2. System functions that allow you to assign, deassign, close, 
rename, and append files 

3. System commands that create a direct-access file and divert 
terminal input and output to other devices 
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This chapter focuses on the following: 

1. Access methods 

2. APL file input and output functions 

3. Basic file system functions 

4. Sequential files 

5. Random-Access files 

6. Utility system functions 

7. Synchronizing shared-file access 

8. Handling I/O from non-terminal devices 

1.2 ACCESS METHODS 



The methods that you use to store or retrieve data in a file are 
determined by the file's organization. The organization of a file is 
fixed at the time you create it, but, depending on the access allowed, 
an access method can change each time the file is opened. In some 
cases, you can vary the access during function execution or during 
immediate mode. You can use two types of record access: sequential 
or random. Sequential indicates that the records are accessed in a 
serial order; random indicates that records can be accessed directly 
at any point in the file. 

Table 7-1 shows the relationships between file organization and record 
access. 

Table 7-1 
Access Methods 



File Organization 


Access Method Allowed 


ASCII sequential 


Sequential only 


Internal sequential 


Sequential only 


Direct access 


Sequential and random 


Binary access 


Sequential and random 



The following sections discuss each type of record access. 



7.2.1 Sequential Access 

All file organizations allow you to access records sequentially. 
Sequential record access is employed when you issue a series of 
requests for the next record. The record operations are performed 
in terms of a predecessor-successor record relationship. For each 
successfully accessed record (except the last) there is a succeeding 
record somewhere in the file. 
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Sequentially organized files (ASCII sequential, internal sequential, 
and binary-access sequential) allow only sequential access. In these 
files, each record except the last is physically adjacent to the next 
record. Sequential access to a sequential file means that records are 
accessed in the order of their insertion into the file. A particular 
record can be read only after each preceding record has been success- 
fully read. Similarly, once a record has been read or written, you 
must reposition the file to the beginning before preceding records 
can be accessed. 

When you assign a sequential file with either the /AS switch (ASCII 
sequential) or the /IS switch (internal sequential) , APL positions the 
file pointer at the beginning of the file. You must then do sequen- 
tial reads to get to the particular record you want. If you do a 
write operation at the beginning of the file, you overwrite the exist- 
ing file, not just the existing record. 

When you assign a sequential file with either the /AS* switch or the 
/IS* switch, APL positions the file pointer at the end of the file. 
You can then append records to the end-of-file with a write operation; 
a read gets an end-of-file. 

Direct-access and binary-access files can be accessed sequentially. 
Sequential access to a direct-access or binary-access file means that 
records are accessed in ascending order according to record number 
(for direct-access) or word number (for binary-access) . A sequential 
read from one of these files finds the next record by adding 1 to the 
value of the record/word number used in the previous I/O operation. 

Binary-access files allow the writing of data based on word position. 
Empty words are assigned a value of integer 0. Direct-access files 
allow, empty record positions that can be caused by a record deletion 
or by your purposely leaving positions empty. APL maintains the 
predecessor-successor relationship through its ability to recognize a 
record position as either empty or occupied. 



7.2.2 Random Access 



Random access allows you to control the order of record access. The 
predecessor-successor relationship has no effect on random access. 
You identify each record of interest in each operation. This pro- 
cedure allows you to access records in any order at any point in the 
file. Random access is not permitted on ASCII and internal sequential 
files because of the strict physical relationship maintained among 
records. Direct-access and binary-access files do allow random access, 

By specifying a record number in a direct-access file or by specifying 
a word number in a binary-access file, you can access any record in 
the respective file. You can also alternate the type of access to 
these files, sequential or random. 

Records in APL random-access files are called components. There is no 
restriction that all records in these files be the same length. 
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7.3 FILE INPUT/OUTPUT FUNCTIONS B AND B OR . IQ AND . OQ 

You can initiate input and output to and from a file either in immedi- 
ate mode or during function execution. When you perform a read oper- 
ation, you are requesting input data from the file. When you perform 
a write operation, you are outputting data to the file. 

APL provides two quad functions for files, one to perform file input 
and one to perform file output: B (.IQ) and @ (.OQ). These functions 
work in much the same way as the basic quad input and output functions 
described in Section 2.5. The file input and output characters are 
formed by overstriking the quad (D) with either the left arrow (-<-) or 
the right arrow {^) . 

The syntax of the I/O functions is explained with each file organiza- 
tion. 



7.4 BASIC FILE SYSTEM FUNCTIONS 



The following sections describe four basic system functions that per- 
form the following file operations: 

1. Assigning a file BASS 

2. Deassigning a file DDAS 

3. Closing a file DCLS 

4. Renaming a file DRENAME 

The names of these system functions, like those described in Chapter 
4, begin with a quad (D) character and are considered to be distin- 
guished names. That is, you cannot use them for user-defined function 
names, and you cannot copy, erase, or collect them in a group. 



7.4.1 PASS - Assigning a File 

Format 

Di4-S'5'' [[channelJI filename [[password]j[[/f ile orgjj [[/share ll/dumpjj ' 

where 

channel is an integer scalar in the range 1 through 12 inclusive. 
If you do not specify a channel number, APL assigns you one. 

filename identifies the name of the file to be read or written on 
the specified channel. The filename has the same format as a 
workspace filename. See Section 5.1.3.1. 

password is optional. The default is (-) . 

/file org is one of the file organizations listed in Table 7-2. 
If you do not specify this switch, the default is /DA. 
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/share is a switch that allows you to extend multiple-user char- 
acteristics. It is relevant to direct-access and binary-access 
files only (Sections 7.6.2 and 7.6.5). 

/dump is a switch used for magnetic tape I/O. It is relevant 
only to binary-access files (Section 7.6.8.1). The single 
quotation marks are required. 

The UASS system function assigns a file to a specified channel number, 
In this way, you can refer to the channel number rather than the 
filename specification when performing I/O. You can also use UASS to 
return information concerning a file. By specifying the channel as 
the argument, you receive the name of the file currently assigned to 
that number plus any other characteristics you may have specified 
previously. 

For example : 

\ oAss 2 
D X R ACC » EXM I" A f 20A1 Z'^'f^ 



If the channel you specify is currently unassigned, APL returns a null 
vector. 

The UASS system function operates in the same manner as any other (APL 
function. UASS returns the value that is the channel number you 
assigned. Therefore, you can specify a variable to receive the value 
of the channel number. 

For example : 

CHPltii-Qf^SS ' TEST /AS ' 
CHAN 

:12 



Because the range of channels is 1 through 12 inclusive, you cannot 
access more than 12 files simultaneously. If you do not specify a 
channel, APL assigns an available channel in the system and returns 
this number as the function result. If you assign a channel number 
(for example 12) that has already been assigned to a file, APL closes 
the first file and deassigns it from the channel, then assigns the new 
file to that channel number. If a syntax error is encountered in the 
UASS function or if there are no available channels, APL returns a 
function result of 0, which means your assign failed. 

The UASS system function does not cause input or output to be per- 
formed. It establishes a connection between a filename and a specified 
channel. 
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Table 7-2 
File Organization Switches 



File org 
Switch 


Default 
File Extension 


Type of File 


/AS 


.AAS 


ASCII sequential 


/AS* 


.AAS 


ASCII sequential; file is posi- 
tioned at end of file to allow 
appending 


/IS 


.AIS 


Internal sequential 


/IS* 


.AIS 


Internal sequential; file is 
positioned at end of file to 
allow appending 


/DA 


.ADA 


Direct-access which supports 
reading and writing 


/DI 


.ADA 


Direct-access which supports 
reading only 


/BS 


.ABI 


Binary-access which supports 
reading or writing, but not both; 
file can be read by multiple 
users, but written by only one 
user at a time 


/BS* 


.ABI 


Binary access; file is posi- 
tioned at end of file to allow 
appending and same user capa- 
bility as /BS 


/BU 


.ABI 


Binary-access which supports 
reading and writing; file can be 
used by only one user at a time 



7.4.2 UDAS - Deassigning a File 

Format 

UDAS channel (s) 

where 

channel (s) is either a numeric scalar or vector, or a null 
vector. 

The UDAS system function deassigns the files on one or more channels 
in the system. In general, UDAS reverses the operations performed by 
the UASS system function. It disassociates the channel number (s) with 
the file(s). If the files associated with the channel numbers being 
deassigned have not been closed (UCLS) , UDAS closes these files 
automatically. 
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Like the UASS system function, UDAS returns a function result. In all 
cases, this result is a null vector. 

For example : 



This example outputs a blank line and deassigns the file associated 
with channel 1. The following example deassigns files from three 
channels: 

Oii'As 2 3 5 



You can deassign the files on all channels by specifying a null vector 
as the argument (or il2). 

For example : 

i:|i:.AS xo 

flSAME AS 

[:|x:.AS Kl.2 



7.4.3 UCLS - Closing a File 



Format 

UCLS channel (s) 



where 

channel (s) is either a numeric scalar or vector, or a null 
vector. 

The UCLS system function closes the files on one or more channels in 
the system. However, UCLS does not deassign the channel from the 
file. This capability is useful when you want to return to the be- 
ginning of a sequential file after performing an operation. After 
you close the file, the next read operation reads the first record in 
the file; the first write truncates the file. There is no need to 
reassign the file to the channel. 
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The following example closes the file associated with channel 2 

QCLS 2 



The UCLS system function always returns a null vector as a result, 
You can specify more than one file or all files. 

For example : 

0("i-"> 2 3 
i:icL.s xo 

flSAME AS 



7.4.4 UBENAME - Changing the File Specification 

Format 

'filespec' URENAME channel 

where 

filespec is the new file specification. You can specify all or 
part of a new file spec. Every element except the name is 
optional. The single quotation marks are required. 

channel is the number associated with the file. 

Specifying elements of the filespec-a new device name, extension or 
filetype, protection code, or directory- is optional. The old value 
is the default. 

The URENAME system function renames a currently assigned file. There- 
fore, before you can use URENAME, you must assign the file with UASS, 
When you execute URENAME , you also close the file if it is open. 

If other users have the file open when you issue a URENAME, the 
URENAME will fail, but the close will be done in any case. Also, if 
other users have the file assigned but not opened (have not performed 
a read or write) they cannot use the file until they reassign it under 
the new name. However, you, the user performing the URENAME, will 
automatically have the file reassigned on the same channel under its 
new name . 
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For example 



PASS ' TEST/ as; ' 

' HEW ' |;;(f;:ek'AME 
w A s T- E s r- ^ f-^i A s I" 4 y 2 4 :.'l / ^■■> -^ 

a ASS :i.o 

HEW, A AS i::4y204::i/'^^^=' 



7.5 SEQUENTIAL FILES 

APL supports three types of sequential files: ASCII sequential inter- 
nal sequential, and binary-access sequential files {/BS and /BS*) . 
The first type, ASCII sequential, is a standard operating system ASCII 
sequential file that can be read or written by APL or by other lan- 
guages. This file format is line-oriented; a record is delimited by 
a carriage return. Therefore, each line is considered a record in the 
file, and records in the file can be of different lengths. You can 
display ASCII sequential files on terminals and high-speed printers. 
To display an ASCII sequential file on the terminal, return to oper- 
ating system command level and type a standard system command: 

TYPE filename 

To display such a file on a line printer, type the operating system 
command : 

PRINT filename 

The second type of sequential file, internal sequential, is a file 
that can be read or written only by APL. In this file format, infor- 
mation is read and written in internal binary format. In internal- 
sequential files, a record is all the data written to the file in a 
single output operation, rather than a single line in an ASCII sequen- 
tial file. 

The third type, binary-access sequential, is a file that can be read 
or written by a file in another language such as FORTRAN, as well as 
APL. 

APL does not open a sequential file for input or output until the 
moment when the first read or write request is made. APL does not 
normally close the file until you direct it to do so with a UDAS or 
UCLS system function, or a )LOAD, ) CLEAR, )OFF, or ) CONTINUE system 
command. This implies that if user A is writing a sequential file and 
user B subsequently starts to read the same file, user B will read the 
copy of the file that does not have the updates just made by user A. 

If your first reference to a sequential file is an input request (read] 
all subsequent I/O requests to that file must be input requests, until 
you close the file. Similarly, if the first file reference is an 
output request, all subsequent I/O requests must be output requests. 
Note that you can store sequential files on many types of system 
devices. 



7-9 



THE FILE SYSTEM 



The following subsections describe the way in which I/O functions for 
ASCII sequential and internal sequential file organizations are for- 
matted. The description of binary-access files begins at Section 7.6.4 



7.5.1 ASCII Sequential I/O 



The following format requests input from an ASCII sequential file: 

S H [mode] 11 channel 

where 

is the input quad function. 

[mode] is one of the integer scalars listed in Table 7-3. It 
specifies both the type of data and the character set of the data 
being read, mode is optional but, if present, you must enclose 
it in square brackets. 

channel is the channel number associated with the file. The 
value of the B function is the data read. 

The following format requests that output be written to a file: 

data B [rnode]!^ channel 

where 

data is the information you want to write to the file. 

@ is the output quad function. 

[mode] is one of the integer scalars listed in Table 7-3. It 
specifies both the type of data and the character set of the data 
being written. mode is optional, but if present, you must en- 
close it in square brackets. 

channel is the channel number associated with the file. The 
value of S is data. 

Because you can write different types of data to a file, you must tell 
APL how to read the data by specifying an input mode. When reading, 
you also specify whether the record was written with mnemonics or with 
the APL character set. Table 7-3 lists input modes and their meaning. 
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Table 7-3 
Input Modes 



Input 


Type 


Character 


Set 


Mode 


D 




TTY 




1 


E 




TTY 




2 


E 




TTY 




3 


D 




APL 




4 


E 




APL 




5 


M 




APL 




6 



The default input mode for TTY is 1; the default input mode for APL 
is 4. For more information on input quad types, refer to Section 2.5. 
For B, modes 1, 2, and 3 are equivalent and modes 4, 5, and 6 are 
equivalent. When accessing APL, you have the option of specifying a 
particular APL character set on output when you respond to TERMINAL.. 
with TTY. The modes 4, 5, and 6 use the setting you specified at 
access time. See Section 1.2 for terminal designators and Section 7.9 
for ) INPUT and ) OUTPUT to non-terminal devices. 

When you are reading or writing to an ASCII sequential file, the first 
thing to do is to assign the file to a channel. If you want to append 
to the file, specify /AS*. For example: 

l"|ASs ' 2 f:i:i...h=:/aS)Ii: ' 



When you are writing to a file, using the output quad S is the same 
as using n-<-A , except that the output is written to a file and not the 
terminal. A record is a string of ASCII characters terminated by a 
carriage return. APL inserts the carriage return/line feed into the 
data. The current width value associated with the active workspace 
is used to determine the maximum length of the line to be output. 
This means that the current page width determines the length of the 
record if the data is longer than the [maximum. APL inserts a carriage 
return/line feed when you reach the maximum setting. You can change 
the setting with the UPW system variable (Section 4.2.15). You can 
also divert output to devices other than your terminal with the ) INPUT 
and ) OUTPUT commands. Section 7.9. If you output to a line printer, 
you should change the width value to 130. 
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The following example illustrates the writing and reading of an ASCII 
sequential file. If data is an expression, you must enclose it within 
parentheses. 

IJASS ' 2 OUTPUT/AS ' 



flg USE:S the a PL CHAPACTER SET 
flTEFilMilNAL IS AN L..A37 

' !-■ :i: P: S T F: E C O P r> ' EJ 2 
l-XPST PECORD 

' S E C O ti I' F-: E C D F< i:> ' fK 2 
SECONX:> HirECOPD 

(2 4fl8)i;!l2 

:l. 2 3 4 

5 6 7$;) 
OCI...S 2 

i!3i:5::i2 

FXPST PECOPX!" 

EL'5:i2 

SECOWXI' Fi:ECOPX:' 

ti;ii:;4::i2 
.1 2 3 4 

r;ii:;4;:i2 

5 6 7 8 

rA 
75 



In the previous example, the first two records are strings and the 
third record is a numeric expression. To read the output, you first 
close the file because you cannot do both input and output at the same 
time. You do not need to assign the channel; DCLS does not deassign 
the channel. 

Notice that, because the numeric expression is a matrix, APL had to 
insert a carriage return/line feed to format it properly. Therefore, 
even though you write an array as one record, it resides in the file 
as more than one record. For example, the above matrix had two re- 
cords when read. 

The expression i4-^BC4]2 requests input and assigns the value to A. 
Since the file pointer was at the end-of-file, the value was a null 
array. The pA returns the null array of shape 75: the error number 
is 75. (See Appendix A for error messages). This error message means 
end-of-file. A blank line in a file is ignored in mode Cl] and is a 
null vector in modes [2] and [3]. A blank line is ignored in mode [4-!] 
and is a null vector in modes [5.1 and [6]. 

To write to the end of an ASCII sequential file, assign the file with 
the /AS* switch. This positions the file pointer at the end of the 
file so you can append to it with write operations without overwriting 
current records. A read to a /AS* file gives an EOF. 
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7.5.2 Internal Sequential Files 

The following format performs a read from an internal sequential file: 

S channel 

where 

B is the input quad function. 

channel is the channel number assigned to the file. The value of 
@ is the data read. 

The following format writes a record to an internal sequential file: 

data channel 

where 

data is the information you want to write into the file. 

S is the output quad function. 

channel is the channel number assigned to the file. The value of 
B is data. 

When performing I/O on internal sequential files, you need not specify 
an input mode as you do with ASCII sequential files. Information in 
an internal sequential file is stored in the internal format of APL, 
which is very different from ASCII format. No conversion effort is 
incurred by using internal sequential files; compared with ASCII 
sequential files, there is practically no overhead involved in reading 
and writing internal sequential files. 

When you are reading or writing an internal sequential file, the first 
thing to do is to assign the file to a channel. If you want to append 
to the file, use the /IS* switch. For example: 

OASS ' INT/lS* • 



In an internal sequential file, a record is all the information pre- 
viously written in a single output operation. A single read will 
retrieve all information output at a single write rather than a single 
line that would be retrieved by an ASCII sequential operation. Also, 
when you write an array to an internal sequential file, APL includes 
the shape of the array along with the array itself. Therefore, you 
need only a single read to retrieve the array. The array is stored in 
one record. 
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Another comparison between ASCII sequential and internal sequential is 
that 7 5 indicates end-of-file in internal sequential as well as ASCII 
sequential. A blank record in /IS returns blanks. For example: 





OASS ' JINT/IS ' 




4 








< TOI"S-10\«'==I- 


' H4 


TOH=S- 


..:l.o\APi... 






' TOF=S--20\'^^P'- 


'EI4 


TOPS-- 

:l. 


(2 4/M8)tl4 
2 3 4 




5 


6 7 8 
OCI...S 4 

B4 




TOFS-- 


■■lC)\Mn.. 
£14 




•ror=-i3-. 
;l. 


••20\«'==i-- 

B4 
2 3 4 




5 


6 7 8 
Ii;i4 

(ME A 

f A 




75 







Note that internal sequential files can reside on many system devices. 



7.6 RANDOM ACCESS FILES 



The following sections describe the characteristics of files that you 
can access randomly as well as sequentially: direct-access files and 
binary-access files. 



7.6.1 Direct-Access Files 

A direct-access file is structured as a collection of variable-length 
records with a directory containing pointers to each record. A record 
can be any size. A direct-access file can reside only on disk but the 
only limit imposed on the size of the file is the amount of disk space 
available. You must specify the number of records you plan to write 
to the file when you first create the file. Unlike the procedure for 
creating ASCII sequential, internal sequential, and binary-access 
files, the procedure for creating a new direct-access file requires 
that you use a system command, ) CREATE. 
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The ) CREATE command has the following format: 

)CREATE filesize filespec 1 password]] blocking factor|| 

where 

filesize is an integer that specifies the number of records you 
plan to write. You are only limited by the amount of disk space 
you have available. 

filespec is the device name, filename, extension or type, direc- 
tory, and protection code. See Section 2.1.4. Everything but 
the filename is optional. 

password is optional. The default is a hyphen (-) . (Direct 
access is the only file type with a password.) 

blocking factor is one of the following values: 8, 16, 32, 64, 
and 128 words. The default is 16 words. 

When you specify the ) CREATE command, APL sets up the parameters of 
the new file according to your specifications. It creates a directory 
that acts as an index for the file. The filesize determines how many 
records the directory, and subsequently the file, will contain. For 
every record you write, there is an entry one word long (36 bits) in 
the directory. This entry contains information about the record such 
as its file position and its size. This directory allows you to 
access records randomly by the number position in the file. The 
directory keeps track of where the records are. 

Because you can delete records in direct-access, there is another area 
in the file called the free-space area. The free-space area keeps 
track of where the holes are in the file. When you delete a record, 
an entry is made in the free-space area. 

The blocking factor you specify with the ) CREATE command allows you to 
allocate space more efficiently in your file. By specifying a block- 
ing factor you actually set up a fixed length for each record. If the 
data you enter is less than the number of words you need to block it, 
APL fills the rest of the record with nulls. For example, if you 
specify a blocking factor of 16 words and the data you enter is 35 
words, the record will occupy 48 words of space. By specifying a 
smaller blocking factor, this type of waste can be minimized but 
writing records with smaller blocking factor takes longer if the 
record lengths are bigger than the blocking factor. 

Note that you do not need to use the ) CREATE command for direct-access 
files that already exist. Once you create a direct-access file, its 
characteristics remain until you delete the entire file. 



7-15 



THE FILE SYSTEM 



7.6.2 Sharing Direct-Access Files 

Before you do any I/O on a direct-access file, you must assign it to a 
channel with UASS. Because you can share direct-access files, you 
have the option of specifying one of three switches with the UASS 
operation. They are: 

/DI multiple-user access; file can only be read. 

/DA single-user access; file can be read and 

written only by one user at a time. 

/DA/SHARE multiple-user access; file can be read and 

written. 

If one user opens a file in /DA mode and another user attempts to 
access the same file in /DA or /DA/SHARE mode, the operation will fail 
and the error message 3 2 FILE BEING MODIFIED will be displayed. 

Sharing of direct-access files is synchronized by the UENQ and UDEQ 
system functions described in Section 7.8. 



7.6.3 Direct-Access I/O 

The following format performs a read from a direct-access file: 

S [[[recordlj] channel 
where 

S is the input quad function. The value of S is the data read. 

[record] is the component number of the record you want to access 

If [record] is not specified, the default is the next record. 

If [record] is specified, you must enclose it in square brackets. 

channel is the channel number of the file. 
The following format writes a record to a direct-access file: 

data S II [record] I channel 
where 

data is the information you want to write to the file. 

S is the output quad operator. 

[record] is the component number you want associated with the 
record. The default is the next record position after the last 
operation. 

channel is the channel number associated with the file. The 
value of the @ is data. 
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The following format writes the record at the end: 

data UAPFEND channel 
where 

data is the information you want to write to the end of the file. 

UAPPEtlD is the system function that allows you to write to the 
end-of-file. 

channel is the channel number associated with the file. 

The value of UAPPEND is data. 

UAPTEND acts like @ except for where the new record is logged into the 
directory. UAPPEND finds the highest record number used and adds one 
to that number. This becomes the record number of the new record. 
The new record is logged into the directory and the record is written 
for random access. If you proceed to do a read, you will find you are 
at the end-of-file. If you then do another write S, you perform the 
same operation. UAPPEND will not enlarge the maximum number specified 
in ) CREATE. 

When you write a record to a direct-access file, you or APL, associate 
a record number with the data written. For input, you specify the 
number of the record you want to read. Because the directory keeps 
track of the record numbers, you can read and write records in any 
order. For example, you can write record 10 before you write record 
9. If you try to read a record that does not exist, the value of the 
read is a null array. The shape of this array is 75, where 7 5 in- 
dicates an end-of-file. 

To delete a record, write a null array of shape 75 in its place. 
For example: 

<o 75fO)i;Ki::5::i(" 



You can access records both randomly and sequentially. If you do not 
specify a record number in your read or write operation, APL uses as 
the record number, 1 plus the value of the record position used in the 
previous I/O operation. If the current is the first I/O operation 
on the channel, record one, the first record in the file is used as 
the default. 

The following is an example of creating and accessing a direct-access 
file: 

> <:.-. I-: I-;; a r- ii;: :|. q q x.< :i: i-: a c c ^ e ;< m 

[;| <>i IS <:> ' 2 I^' •••■ '■■: <'^ <•• <" » ^'- '•' M / 1-'.' A ' 

»<-<2 4f \B)i;iii;:98::i2 
-RECORD 8'i;iii::8::i2 

RECORD 8 

fi:'<!-Hi::9e::i2 

2 4 
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flNEXT OPERATION WRlTFrS TO RECORD 99 

( \ 4 ) ra2 

12 3 4 

Hr8:."l2 

RECORD O 

IB 1:9 9.] 2 
12 3 4 

D<-i--^;; 2 

For the sake of efficiency, APL will not write a. record across a block 
boundary (128 words) unless the record is larger than 128 words. Be- 
cause of this limitation, it is very inefficient to have files where 
all records are between 65 and 100 words. It is more efficient to 
write fixed-length records. For example, if you realize that all 
records will be between 10 and 32 words, you can specify a blocking 
factor of 32. This will reduce CPU time and the real time involved in 
I/O operations. The file size will, however, be larger than if you 
had specified a blocking factor of 8 or 16. If most of your records 
are larger than 128 words, you should set the blocking factor to 128. 

You can also reduce processing time by updating the file in order of 
record numbers - for example, by writing records 5, 9, and 200 in 
order instead of 5, 200, and 9. When updating a file, you should 
perform deletions first and then replacements and additions. 

The formula for determining the number of words that data (for ex- 
ample, the letter A) will take up, is: 



where 



is 0.5 


to indicate floating-point 


1 


for integer 


4 


for character 


36 


for Boolean 



Note that direct-access files can reside only on disk or drum devices, 



7.6.4 Binary-Access Files 



API. treats a binary-access file as random-access memory. By using a 
binary-access mode, you can access a file of any format or character- 
istics. For example, you can read and write FORTRAN or COBOL random- 
access files with an APL binary-access function. 

To read or write this type of file, you specify the following: 

1. The word of the file at which reading or writing is to begin 

2. The type of values to be found beginning at the specified 
word (for example, integer, ASCII) 

3. The number of values to be read or written 
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Data is stored in variable-length records that you can access randomly 
or sequentially by specifying a word position, rather than record 
position as in direct-access files. 

Because you specify data type when performing I/O (see Sections 7.6.6 
and 7.6.7), you can read or write any type of file organization in- 
cluding ASCII sequential, internal-sequential, and direct-access files, 

For magnetic tapes in binary-access mode, you can perform a variety of 
magnetic tape operations with the UMTP system function. Refer to 
Section 7.6.8.2 for more information on UMTP. 

Binary-access files can be shared with other users. See Section 7.6.5 
for file sharing information. 



7.6.5 Sharing Binary-Access Files 

Before you can perform I/O on a binary-access file, you must assign it 
to a channel number with UASS. You have the option of sharing binary- 
access files with other users. You control the extent of the sharing 
by specifying certain switches with UASS. They are: 

/BS File can be read or written but not both; 

file can be read by multiple users but 
written only by one user at a time. 
Sequential access only. 

/BS* Same access privileges as /BS, except 

sequential output begins at end-of-file. 
Sequential access only. 

/BU File can be read and written; only one user 

can have a /BU file open at any time. If 
another user attempts to read or write a /BU 
file that is already in use, an error message 

3 2 FILE BEING MODIFIED will be returned. 

/BU / SHARE File can be read and written; multiple users 

can simultaneously have the file open. A 
user cannot access a file in /BU /SHARE mode 
if another user has already opened the file 
in /BU mode. 

Note that in the case of /BS and /BS*, on output, if you specify a 
word position that is less than the last word output, you erase the 
entire file and create a new file with your output written at that 
word position. 

The UENQ and UDEQ system functions, described in detail in Section 7.8, 
synchronize the sharing of binary-access files. 
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7.6,6 Binary-Access I/O 

The following format performs a read from a binary-access file opened 

as /BU, /BU /SHARE, IBS, or /B5* : 

S |[Cword!]j| channel [I, header I], type M, length || || || 



where 



S is the input-quad function. The value of S is the data read. 

[word] is an integer specifying the word position at which read- 
ing is to begin. The default is 1 (first word) . The file pointer 
is at either the beginning of the file, or at the next word after 
the previous I/O operation. 

channel is the channel number assigned to the file. 

header is either the value for no header, or 1 if a header is 
available. The default is 1. If you specify header, you must 
specify type and length. If header is 0, APL takes the correct 
type and length from the data. 

type is an integer from 1 to 6, specifying the type of data being 
read. See Table 7-4 for data type values. If a header exists, 
you need not specify type. 

length is an integer indicating the number of values to be read; 
not the number of words. If a header exists, you need not 
specify the length. 



Table 7-4 
Data Types 



Type 


Data 


Value Size 


1 


integer 


1 per word 


2 


Boolean 


36 per word 


3 


single-precision 
floating-point 


1 per word 


4 


double-precision 
floating-point 


1 per 2 words 


5 


APL 9-bit 


4 per word 


6 


ASCII 7-bit 


5 per word 
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The following format writes a record to a binary-access file. 

data a [[[word]]] channel |[, header [[,type f[, length]] 1] ]] 
where 

data is the information you want to write to the file. 

S is the output-quad function. The value of is data. 

Cword.l is an integer specifying where you want the write to 
begin. The default is 1 if the file pointer is at the beginning 
of the file or the next word after the previous operation. 

channel is the channel number associated with the file. 

header is either if the header does not exist, or 1 if the 
header is available. The default is 1. 

type is an integer from 1 to 6 specifying data type. See Table 
7-4. If you do not specify type, APL attempts to write the data 
in the proper type. 

length is an integer indicating the number of values to be 
written. When you specify a header, the length specification is 
ignored. 

The following format writes a record to the end of a binary-access 
file opened as /BU or /BU /SHARE-. 

data UAPPEND channel [[, header [[,type [[, length]] ]] | 

where 

data is the information you want to append to the end-of-file. 

channel is the channel number associated with the file. 

header is either or 1. 

type is one of the data types listed in Table 7-4. 

length is an integer indicating the number of values to be 
written. The value of UAPPEND is data. 

UAPPEND writes to the physical end-of-file. The default word number 
for the next read or write to the file is now the end-of-file. In 
other words, the sequence UAPPEND, then with no word specification 
always gives an end-of-file, while the sequence UAPPEND then @ with 
no word specification appends a second record to the end-of-file. 

To write to the end of a binary sequential file, use the /BS* switch 
when assigning a channel number. Then, the first write operation 
opens the file at the end to prevent overwriting. 

When you write a record with a header, APL sets up the record with the 
header information first. The header size is two words plus one word 
for every dimension in your data. The data type and length make up 
the first word of the header (one half-word each) . The rank of the 
data is in the second word, the number of rows in the third word, the 
number of columns in the fourth word, and so on. 
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Figure 7-1 illustrates the format of the header. 



Bit 
Word 1 
Word 2 
Word 3 
Word 4 








17 


18 


35 


type (1-6) 


length (in words) 
of value plus header 


Rank (Number of dimensions in data) 


rhol 


rho 2 





Figure 7-1 Format of Header in a Binary-Access File 

If you do not specify a header when performing I/O, you must specify 
the type and length of the data for input and output. 

When reading a record with a header, you have the option of actually 
accessing the header information itself or going right to the data. 
If you specify no header (0) on a read of a record with a header, you 
will access the header information when requesting word 1, 2 and so 
on. APL views the header as data in this case. If you specify header, 
APL goes right to the values you input instead. Because APL creates 
a header as the default, if you read the end-of-file without specify- 
ing in the header position, you will receive a 15 DOMAIN ERROR. 

The following example illustrates the writing then reading of a 
character matrix whose shape is 3 by 2. A header is specified along 
with ASCII data type (6) and length (number of values (6)). Figure 
7-2 illustrates the format of the header and the data. 



i;;|Ass ' :| f:i;i...e/bu ' 
:l. 

(3 2r ' ABCDHF- )m. y :l. y5i.6 

(::• i:> 

E i: :i. ::i :i. y o y :l. y :i. 

:l. 3 10726 

ei::2::iiy0y i ■>i 
■"> 

E 1 3 ;:i 1 y y :i. y 1 
3 

E i:: 4 ::i i y o y i y :i. 
I!:ii::5:;iiy0y5y6 

ABCDEF 

nci...i:> 1 



7-22 



THE FILE SYSTEM 



The data is stored as follows: 



type 



5 


1 — ' — — 

6 


2 


3 


2 


A 


B 


C 


D 


E 


F 









length in words 



rank 



rho 1 



rho 2 



values read 



Figure 7-2 Record Format of a Binary-Access File 

Note that the final value word is right-filled with zeroes. 

In the previous example, the first read produced an integer value for 
the entire word 1310726. To break this down into type and length, use 
the encode function as in the following example: 



<0y2A:l.8)Tl31072A 



5 6 



The following examples illustrate the use of the file input and output 
functions for binary-access files: 

pASS '2 BXM/BW 

2 

ft W Y-i: X T III: S fi: III: « U KI; S T J I-I :::: () y ft O I'l Hi: A O B R y T :::: :| j, X it T B. G III: I-: 

( \S)i:si2yO)':i. 

12 3 4 5 

ft w Hi: :i: r ui: s r ih: a u ki: ii> r j s iii: i.i u h ?■< r x a i... 

6 7 8 9 10 11 12 13 

ft i=i: hi: f^ D BEG :i: li N :i: >i o a t' s '^' '■' w o i-;: x:" ; 4 v f^ 1... u 111: s r 1:1: a t< 

i;it:e:]2;'0yii'4 
e 9 10 11 

ft R hi: a x:i j <i> hi: « u ki: it r x a i... i... r' ■■■■ it 111: k t w o i-: x:' 5 2 '^-^ « i- '■■> >^ -> 
1:12 y y :l. y 2 
12 13 

ft w R X T hi: b hi: g :i: f-i u x n o a r 1 3 r i-i w o 1-: x:i j a s c x x d a t a 

■ r O R S .... ;|. « 1=^- 1-- ^ f' ' 1: 1 3 ::i 2 y y 6 
TOPS-.:|. A PI... si- 
ft R hi: AD I woh::x:i X':<iii:g:i:hn:hk'g at 13th woHi:x:i 

Ii3i::i3:i2y0y6y5 

TOPS.- 

ft Hi: hi: a x:- 2 w o i-;; i:' s ( :|. v f-^t 1... u hi: s > < a f >i 111: ;•; y w o r r.< ) 

I;i2y0y6yl0 
:l.0 API...SF 

ftWHi::HTKi: x:<iii:g:i:wn:hng at 50 !'"'■•' wohi:i:i 
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n HEADER EXISTS 

<3 2r20M6)e[:5o::i2 

21 22 
23 24 
25 26 

fl Fi: E A X.I I V A l_ U E S B E G l" M ii X ii G f-^ T 5 () ( M O H Hi! A I- K-: l=i: ) 

i!;ii:5o::i2yOy:i. s'lo 

262154 2 3 2 21 22 23 24 25 26 

ft TR ANSI.. ATE jsT woRiii :i:hto d e c .i: M A I... 

(0i'2Al8)T262154 
1 10 

flREAD Xv<E(:v:niWlNG AT 5() 

iei::5o:]2 

2 !l '■' 2 
23 24 

25 26 

flMUL.L. VECTOR 1 HD :i: C ATES END •OF •■F X I...E 

'^<U32yOylyl 

f A 

75 



If you open a binary-access file with /BS, you can access the file 
only sequentially. Because you can also specify a word number when 
writing to the file, you could destroy the file by specifying a word 
number that is less than the last word number written. For example, 
if the last output was written in word 40, and you specify word 15, 
the data will be written in word 15 but all data before and after that 
word is erased. 

You can, however, write to a word number greater than the last word 
number in the file (41 in this case) . APL considers this preserving 
the sequence. Note the following example: 

C^ H A ii f . |;;| A S B ' B X i>. / B S ' 

( \ 10)i;j|(:-HAH 
12 3 4 5 6 7 8 9 10 

(lOM 10)I:)I<:-HAH 

11 12 13 14 15 16 17 18 19 20 

(40Mio)ei;;5o:]f"HAN 

41 42 43 44 45 46 47 48 49 50 

(iooMio)i;!ii;:3;.i*"HAN 

101 102 103 104 105 106 107 108 109 110 

PCL.S CHAN 

(::■ i-i f^i N i-- 1\ A s s ' B :i: m / b s • 

ii;it::5o::i«"HAN 

:l.5 i:<oma;i;n error 

i[ji::5o::i<:-HAH 

A 

oi:: 3 "I CHAN 

101 102 103 104 105 106 107 108 109 110 

ei:;2::i«-HAN 

15 3[>oma:i:n error 

Eii;:2;:i«"HAN 

As in direct-access files, to delete a record in binary-access, 
specify a null vector in its place (0 75)p0. Also, an end-of-file is 
indicated by the null vector (0 75), pO and the error message 75. 
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With binary-access files, you can also input and output mixed data in 
one logical record. See Section 7.6.7 for the UCIQ and QCOQ system 
functions. 



7.6.7 UCIQ and UCOQ - Accumulating Data 

The UCIQ and UCOQ system functions allow you to accumulate data of 
different types into a variable for storage as one logical record. 

For output, use the following format: 

data UCOQ [[header |[^type|| 
where 

data is the value of UCOQ. 

UCOQ is the system function that packs data for output. 

header is either or 1, with the same meaning as in Section 
7.6.6. 

type is a data type listed in Table 7-4. The value of UCOQ is 
the packed data. 

The following format unpacks data: 

variable UCIQ |header [[/type]]| 
where 

variable is the name where the value being read is stored. 

UCIQ is the system function that unpacks the data. 

header is either or 1. 

type is a data type listed in Table 7-4. The value of UCIQ is 
the packed data. 

The UCOQ system function takes any data type and turns it into an 
integer vector. In this way you can assign UCOQ packed ASCII char- 
acters to a variable and assign floating-point or APL 9-bit to another 
variable and catenate them. Then you can write the record to a file 
with S using the integer data type. 

For example : 

262:1.52 1. 5 :l. 2 3 4 5 

(0 2ai8)t''[:i.:i 

.1. 8 
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To retrieve it and translate the data back, first read the data with 
0, then use UCIQ to unpack the data types. 



For example 



12 3 4 5 



i: 1 :i 

1:2:1 

\::v.-i 

i:5:j 
1:6:1 

{173 

1:8:1 

1:10:1 
1: 1 1 :i 
1:12:1 



A 

n 
n 
n 
n 
n 
f-- 

X 

I"- 
X 



FACKi:a:jv 

apack uses tjcoa to i"ack a set of values :cwto a single 

VARXAE<L.E» THE VALUES CAN BE OF i:"!!: FFERENT TYPES, USE 
APACK when catenate WON'T WOPK 
LIST IS A CM-IAI".:ACTEP MATr-ilIXy EACH ROW OF WHICH CONTAINS THE 
NAME OF A VARIABLE WHOSE VALUE IS TO BE PACKOnX." 
THE RESULTANT PACKEP VALUE •■■■ IT IS AN INTEGER ARPtAY 



r- X 

i-\0 

it 

ST* 

<■■ I .{• 
TES 



•K"i:>ltfi-:i;i^T)/() 
(^LIST|;:IJ:J)l:]c^o« 



1: 1 :i 

1:2:] 

1:3:1 

1:4:1 

i:::^:i 

1:6:1 

1: 7 :i 

i:s:i 

1: 9 :i 

1:10:1 

[; 1 1 :i 

1: 1 2 :j 

i:i3:i 

1: 1 4 :i 

1: 1 5 :i 

1:1 6:1 

1: ;i. 7 :i 

1:10:1 

1:19:1 



vaunpaci<i:;o;]v 
I"- A *■■> i( I"' f^ <:' i< I" :i" s r j .t" f\ r f-^ ; :i: j j j 1... e n j i;;: h t r r 

^UNPACK USES |::|CI« TO UNPACK A VARIABLE CREATEB BY aRACK 

INTO A SET OI-" VARIABLE NAMES,, US I NO ASSIGNMENT 
)■■■ IS THE PACKED VALUE j, CREATED BY aPACK 

I... :i: If; r- i s a c h a i-;.- a c t lii: 1-: m (^ r r--. x x „ ih: a c h i-t o w o i-- w i-i i c h c o h t (^ i n s t h i-i: 

i( A M Hi; o !"■ f>i V f^ F. :i: a b i... i;-: t o 1=:: i;;; c 1:;: i v 1;=: !:■ o f« e o i-- t i-i e r=- a c^ k e d v f>, 1... u li-: s , 
the values unpacked out of p ark;; stored into successive 
variables named in list 



DATA.i" 
Iff DA 

-HI 

T i;;; •■.■; r' * •■;> 
•■> < ■■' > 1 

LENfJ. 
ENTRY 
j^LIST 
.DATAf. 

Ifl.-L 
..jfTEST 



I"- 
TA 

(:i^<.0)/0 

ffLIST)/0 

sKO 2 a18)t»atai:;:i. ;:i 

<.DATA|:; \ LEN"| 

I" Jj) ;:( y > <..ENTRY Qcxa :|, 

LEN.J,DATA 

l:i; ii 



n DEFINE SOME NUMERIC VARIABLES 
Afl 

AAfl 1 
AAAf-l 1 1 

ft D B F I It E S O M E C H A R A C T E R V f^ R I A B I... E <■> 
Bf- ' B ' 
BBi- ' BB ' 
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ft MAKE A I... 1ST OF XNPUT V A R I A B l._ Ki! NAMES 

"-K-^ '3r ' f^ f^f^ AAAB Iv<B ' 

1-1 
A 

A A 
AAA 
B 

ft PACK these: s-* a r. cables into one :i:tem 

H CATENATE W.TI...I... NOT WORK 
Pf-ARACK I... :|. 

52429:1. ■■■■34359738368 524292 :l. 2 •■l 7:1. 79869:184 524292 :l. 
3 ■8589934592 :l. 3:1. 0723 -■2:1.20640:1.024 :I.3:U)724 :l. 2 
"2:1:1.13602048 

flMAKE A I... .TST OF OUTPUT S-* A R X A B I... E NAMES 
L2<"5 3f ' ••< '•''■' 'ww-JV YY ' 

L. '.:> 



H UNPACK THE PREVIOUS BAT A XtiTO THESE NEW V A R X A B 1... Ill 
P aU?(PACK 1.-2 

flTHE RES TORI:-: B DATA :i; S THE SAME AS THE BAT A 
flTHAT WAS PACKEB 







X :::: 


fit 


1 




;.; J.J 


::■.: A A 


:l. 


1 


;.;>-•! 


; :::: AAA 


1 


1 :l 


1. 


; B 


1 




r T" 


:::: BB 


1 


1 







7.6.8 Binary-Access Magnetic Tape Files 

Binary-access mode is often used to read magnetic tape files that have 
been created on other systems. The following sections. Sections 
7.6.8.1, and 7.6.8.2, describe the use of the /BS/DUMP switches and 
the UMTP system function for magnetic tape. 
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7.6.8.1 /BS/DUMP Switches - If you plan to read or write a binary- 
access file on magnetic tape, you should specify the /BS switch when 
assigning the file to a channel {UASS) . Output is then written to a 
binary-access magnetic tape file in fixed-length blocks. The size of 
these blocks is determined by the operating system; the default size 
is 128 words. You can override the setting with the SET BLOCKSIZE or 
SET TAPE RECORD- LENGTH monitor commands. ^ 

If your file consists of variable-length blocks, you should also in- 
clude the /DUMP switch. When you specify /BS/DUMP , each read or write 
request reads or writes one magnetic tape block. 

When you perform a read, the size of each input request must be at 
least as large as the block to be read or you will receive the message 
74 BLOCK TOO BIG. If the length specification in the input request is 
larger than the input block, the value read will reflect the actual 
block size. You should specify length with because APL cannot know 
the length of the data before reading the tape. 

NOTE 

The primary use for /BS/DUMP is to read 
magnetic tapes generated on other 
systems. It is not recommended for 
general use. 



7.6.8.2 UMTP - Operating on Magnetic Tape - The UMTP system function 
performs a variety of magnetic tape operations including rewinding, 
setting density, and returning data modes. 

Format 

channel UMTP operation (s) 
where 

channel is the channel number associated with the file. 

UMTP is the system function for magnetic tape operations. 

operation (s) is a vector containing one or more codes indicating 
the particular magnetic tape operations to be performed. See 
Table 7-5. 

Some of the operations read characteristics of the tape. For each 
read operation the result of that operation is placed into a result 
vector. In other words, if there are 3 read operations in the oper- 
ations array, the result array will be 3 elements long. If there are 
no read operations, the result array will be null. 

There are four basic types of magnetic tape operations. 

1. Tape positioning operations - These operations do such things 
as rewind the tape and move it forward and backward. They 
have codes in the range 0-511. 

2. Read operations - These operations read characteristics of 
the tape such as density and track status. The results of 



^See the TOPS-20 Monitor Calls Manual (version 3A or later) or the 
TOPS- 10 Monitor Calls Manual (version 6.03A or later). 
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these read operations are placed in the result array, as 
explained above. They have codes in the range 512-1023. 

3. Write operations - These operations set characteristics of 
the tape. The value which is written is taken from the next 
element of the operations array. For example: 

12 QMTP 102S 

This example sets the density of the tape to 1600 bpi, the 4 
is the value written as the tape's density. These operations 
have codes in the range 1024-1535. 

4. Reserved for user definition - These must be defined by the 
user. Since APL does not know whether these are read or 
write operations it assumes they are both. In other words, 
it passes the next element of the operations array to the 
operation and puts the result of the operation in the result 
array. These operations have codes in the range 1536-2047. 

On TOPS-10 the operation codes and results returned are identical to 
those for the TAPOP UUO. (See the TOPS-10 Monitor Calls Manual .) On 
TOPS-20 the operations listed in Table 7-5 are available. 

Table 7-5 
Operation Codes 



1 - 


Wait 


for I/O to stop 


2 - 


Rewind the tape to the load point 


3 - 


Rewind and unload the tape 


4 - 


Skip 


forward one block 


5 - 


Skip 


forward one file 


6 - 


Skip 


to the logical end of the tape 


7 - 


Skip 


backward one block 


8 - 


Skip 


backward one file 


9 - 


Write a tape mark | 


513 - 


Read 


density, possible values are 




- 


unit default bits/inch 




1 - 


200 bits/inch 




2 - 


556 bits/inch 




3 - 


800 bits/inch 




4 - 


1600 bits/inch 




5 - 


6250 bits/inch 




6-17 


- reserved for DIGITAL 


519 - 


Read 


data mode, possible values are 




- 


DEC-compatible core dump format (7-track and 
9-track) 




1 - 


DEC-compatible dump format (9-track) 




2 - 


Industry-compatible, 8-bit mode (4 bytes/word) 




3 - 


6-bit mode (9-track, TU70 only) 




4 - 


7-bit mode (TU70 only) 




5 - 


DEC-compatible 7-track core dump (SIXBIT) 


520 - 


Read 


track status, l=7-track, 0=9-track 


521 - 


Read 


write-lock bit; returns 1 if set, if not set 


1025 - 


Set density (same values as read) 


1031 - 


Set data mode, same values as read 
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On success, UMTP returns a l-dimensional array with one element for 
each read or user-defined operation. If any of the operations returns 
an error, UMTP returns an integer indicating the cause of the error. 
For TOPS- 10 the errors are the same as for the TAPOP UUO. For TOPS- 20 
the following errors can be returned: 

-2 Unknown error 

-1 Address check while storing answer 

Illegal function code specified 

1 Function code requires privileges 

3 Value is not in legal range 

4 Address check while reading arguments, or too few arguments 
6 Tape has not been initialized 

8 Termination code error 

9 Job number associated with unit is incorrect 

In addition, for both TOPS-10 and TOPS-20, the following errors can be 
generated : 

12 RANGE ERROR - CHANNEL < 1 or CHANNEL > 12 

6 4 CHANNEL NOT ASSIGNED - CHANNEL not assigned 

9 RANK ERROR - Rank of argument array NEQ 1 and length 

of argument array NEQ 1 
15 DOMAIN ERROR - Operation code LSS 

10 LENGTH ERROR - Write operation specified but there is 

no argument to write. 
6 2 NOT A PROPER DEVICE - Device is not a magtape 



NOTE 

When you specify UMTP, APL first writes 
out any in-core buffers before perform- 
ing the UMTP operations. You should 
therefore issue this function with 
great caution, and you should use it 
only between magnetic tape files. 



7.7 UTILITY SYSTEM FUNCTIONS 



The following sections describe four utility system functions that 
return file organization, device characteristics, record size, and 
other information about files that are in the system. 
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7.7.1 UCHS - Returning File Organization and Status 



Format 



UCHS channel(s) 



where 

UCHS is the system function. 

channel (s) is one or more channel numbers associated with the 
files. 

The UCHS system function returns the file organization and the open 
status of the files on one or more channels in the system. The 
channel argument can be a numeric scalar, vector, or a null vector. 



For example: 



i;:|CHS B 



4 :l 



This expression returns information about the file associated with 
channel number 8. If the channel number is a vector, APL returns 
information on all channels specified. One row containing two values 
is returned for 6ach channel specified. The first value identifies 
the file organization, and the second value identifies the open status 
of the file. 

Tables 7-6 and 7-7 list the meanings of the values. 



Table 7-6 
File Organization 



Code 


Organization 





channel free 


1 


/AS 


2 


/IS 


3 


/DI 


4 


/DA 


5 


/BS 


6 


/BU 
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Table 7-7 
Open Status 



Code 



Status 



channel free 

file assigned but not open 

file open for output 

file open for- input 

file open for input and output 



If you specify a single channel number, the result of the function is 
a 2-element vector. If the function contains N arguments, the result 
is an array of shape N hy 2 . For example, the following function 
results in a 3-by-2 array: 



OM- :i:L.s<!-.ncHS ^3 



4 :l. 

5 1 




f F ;i: I... s 



If the argument to UCHS is a null vector; 





UCHS 


\0 


4 


1 







i 













iS 


1 












4 


1 




4 



1 






















1 


1 





APL returns information on all channels in the APL system, 
specification is the same as UCHS il2. 



This 
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7.7.2 UDVC - Returning Device Characteristics 

Format 

UDVC channel (s) 

where 

UDVC is the system function. 

channel (s) is one or more channel numbers associated with files. 
This argument can be a numeric scalar, vector, or a null vector. 

The UDVC system function returns a device-characteristics word and 
block size for the files on one or more channels in the system. The 
device-characteristics word returned by UDVC has the same format and 
meaning as that interpreted by the DEVCHR UUO^ . 

The syntax is identical to that of UCHS: one row containing two values 
is returned for each channel specified. The first value is the device- 
characteristics word, and the second value represents the block size 
for the device, in words. UDVC returns a 2-element vector if a single 
channel is specified. If the function contains N arguments, the re- 
sult is an array of shape N hy 2 . If the argument is a null vector, 
APL returns information on all channels, and the result is an array 
of shape 12 by 2. 

It is usually helpful to convert the device-characteristics word to 
binary format before examining it. The following example illustrates 
the conversion of the word returned in the example included at the 
beginning of this section with the APL encode function (t) . 

For example : 



4 :l 

Ai::ij 

;l 7324376063 

'01 ' i;::i.t(36f2) Tfti::i::i::i 

1 000000 1000 1 00 1 1 :l. 00 :l. 1 1 1 :l. 1 1 1 1 1 1 1 1 1 1 1 



LPT: 
DSK: 



MTA: 
TTY: 



^ Device can do output 
I — Device can do input 



^See the TOPS-20 Monitor Calls Manual (version 3A or later) or the 
TOPS-10 Monitor Calls Manual (version 6.03A or later). 
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7.7.3 UFLS - Returning File Sharing Information 

Format 

UFLS channel (s) 



where 

UFLS is the system function. 

channel (s) is one or more channel numbers associated with files. 
The argument can be a numeric scalar, vector, or null vector. 

The UFLS system function returns the sharing status and other infor- 
mation about files on one or more channels in the system. The syntax 
of UFLS is similar to that of UCHS and UDVC except that one row con- 
taining four values is returned for each channel specified. The mean- 
ing of the values differs according to the file organization. UFLS 
is meaningful only for direct-access and binary-access files. If the 
channel number you specify is associated with an ASCII sequential or 
internal sequential file, the values returned are all zeros. 

The values returned for direct-access files {/DA and /DI) have certain 
meanings depending on their position in the vector. Starting from 
left to right: 



First value 
Second value 

Third value 

Fourth value 

Starting from left to 
the following meaning 

First value 
Second value 

Third value 
Fourth value 



Share bit: means no sharing, 1 means 
sharing 

Value of the next record number to be used 
for reading or writing (if subscript record 
in the file I/O request is defaulted) 

Maximum record number permitted 

Blocking factor 

right, the values for binary-access files have 



Share bit: means no sharing; 1 means 
sharing 

File-word pointer to the next word to be 
read or written (if subscript word in the 
file I/O request is defaulted) 

Length of file in words (cannot be deter- 
mined for magnetic tape device) 

Size of last read or write request in words 
(Not for magnetic tapes) 
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For example: 



PFL.S I 

20 2052 SO 



There is another important difference between UFLS and UCHS . The file 
on the channel must be open to return values. In the case of a /BS 
file in which only reading or writing can be in effect at any one time, 
there must be a way of specifying which type of access you intend to 
perform on the next operation if the file has not already been accessed, 
APL allows you to include a special channel number specification for 
/BS files that have not already been accessed. A channel number in 
the range 1 through 12 indicates that you will be reading the file. 
A channel number in the range 101 through 112 indicates that you will 
be writing the file. 

UFLS returns a 4-element vector if a single channel number is speci- 
fied. If the function contains N channels, the result is an array of 
shape ^ by 4 . If you specify a null vector, APL returns information 
on all channels, and the result is an array of shape 12 by 4. 



7.7.4 UFCM - Returning File Information 

Format 

UFCM channel 

where 

UFCM is the system function. 

channel is the channel number associated with the file. 

The UFCM system function returns information about the records in a 
direct-access file. Unlike UCHS and the other utility function, the 
UFCM function requires that the channel number be an integer scalar, 
not a vector. UFCM is meaningful only for direct-access files i/DA 
and /DI files) . If the channel number is associated with another file 
organization, the result will be a null array of shape by 2 . 

For direct-access files, UFCM returns one row containing two values, 
one row for every record in the file. The first value is the record 
number; the second value is the number of blocks in the record. If 
the file contains N records, the result is an array of shape N hy 2 . 

For example : 

|;;(FCM 3 

:l. ;l. 

4 63 

56 7 

76 7 

98 :l. 

99 :l. 
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7.8 UENQ AND DDEQ - SYNCHRONIZING SHARED FILE ACCESS 

Format 

UENQ channel lock number share bit 
UDEQ channel lock number share bit 

The UENQ and UDEQ system functions allow you to synchronize access to 
shared direct-access and binary-access files. These functions should 
be used only by advanced APL users familiar with the ENQ and DEQ moni- 
tor calls. ■"• In addition, the issuing of UENQ and UDEQ functions 
should be restricted to a cooperating group of users who require 
shared access to common files and who have decided upon a mutual pro- 
tocol for synchronizing file usage. 

Synchronization of file access proceeds as follows: A user assigns a 
file and specifies that it is to be available for shared access 
{/SHARE) . However, to protect the file while a read or write is being 
performed, some method is needed for temporarily locking the file from 
access by other users. UENQ performs this lock function. The file 
remains under the control of the user who issued UENQ until that user 
releases it for continued shared access with the UDEQ function. The 
arguments to both functions specify the degree to which the file is 
locked against other users. 

The first two arguments, channel number and lock number, are con- 
sidered a lock pair. The first element identifies the channel number 
on which the file to be shared is assigned. The second element repre- 
sents the particular type of lock being performed. Depending on the 
conventions adopted by file users, this number might be a file record 
number, a range of record numbers, or some other representation. The 
lock number must be in the range through 2*33-1. It has no inher- 
ent meaning to APL; its only significance is that agreed upon by 
cooperating users. The share bit is discussed later in Section 7.8.3. 

The channel number is not particularly significant. The file to be 
shared must be associated with the specified channel, but several 
users can have the same file assigned to several different channels. 
This is illustrated in the next example. The chronological order in 
which operations are performed is significant and proceeds from top to 
bottom. 

USERm-, 20^1 USERLH,20b:\ 

UASS '12 FRT/BU/ SHARE' UASS »11 FRTL5 5 ,121 /BU / SHARE 

12 11 

UENQ 12 9 9 


FILE OPERATIONS ON 12 UENQ 11 9 9 

USER ENTERS A WAIT STATE 

UDEQ 12 99 


FILE OPERATIONS ON 11 



UDEQ 11 9 9 



^See the TQPS-20 Monitor Calls Manual (version 3A or later) or the 
TOPS-10 Monitor Calls Manual (version 6.03A or later). 
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You issue UENQ and UDEQ on lock numbers as well as on channel numbers. 
An UENQ succeeds if another user is not already enqueued on the speci- 
fied lock. If the lock is currently enqueued, the second user enters 
the wait state until the first user issues a UDEQ to free the locked 
file. When you close a file, all locks on the channel associated with 
the file are dequeued. 

A successful UENQ or UDEQ returns a as' the function result. If an 
error is encountered, a scalar value representing the error condition 
is returned.^ A return code of ~1 means that the system does not 
support the use of UENQ and UDEQ. 

Only the channel number is required in an UENQ or UDEQ specification. 
The function: 





is equal to: 

aHH« 6 



You can specify a matrix as an argument. 
For example: 

|;;|ih;n« m 



Af is a matrix in which each row specifies a lock pair. APL enqueues 
on all locks specified in this matrix. All locks must be successful 
for an UENQ to succeed. 

If you include only a channel number with UDEQ, APL clears all locks 
on the file. If you include a null vector as a channel number, APL 
clears all locks on all channels. For example, the UDEQ expression: 

i:f:'|;^« 3 :i.r 5 6 7 





clears all locks on channels 5, 6, and 7. 



^See the TOPS-10 Monitor Calls Manual (version 6.03A or later) for 
an explanation of value errors returned under TOPS-10. 
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7.8.1 File Locks 

The lock pair: 

UEI^Q channel 
UDEQ channel 

has special significance in APL. This lock pair is considered to be 
the file lock and is used primarily by the file system itself to 
control access to shared files. APL automatically issues internal 
UENQ and UDEQ functions on the file lock for the following organiza- 
tions: 

/DA and /DA /SHARE 

/DI 

/BU/SEARE 

These functions are performed to ensure efficient access to the in- 
core disk buffers maintained by APL. 

When you specify a /DA file without sharing, APL issues an UENQ on the 
file lock. When the file is closed, an automatic UDEQ is performed. 
If /DA /SHARE, /DI, or /BU/ SHARE is specified, APL issues an UENQ on the 
file lock when the file access is first issued. It issues an auto- 
matic UDEQ on the file lock whenever a terminal input request is 
expected. Before performing the UDEQ function, APL writes out all 
output buffers and clears all input buffers. 

You can explicitly issue an UENQ function on the file lock. If you do 
this, APL will not issue an automatic UDEQ until you issue a corres- 
ponding explicit UDEQ on the file lock or until the file is closed. 
You can issue an explicit UDEQ function on the file lock at any time, 
thus causing APL to clear all in-core buffers for the corresponding 
file. For certain applications, it is more efficient to issue expli- 
cit UENQ's and UDEQ's. 



7.8.2 Determining Lock Numbers 

The group of APL users who will be sharing files and issuing UENQ and 
UDEQ functions for these files should agree upon the significance of 
the lock-number arguments included in the function lock pairs. As 
previously mentioned, this argument can be any number in the range 
through 2*33-1, where has a special meaning. The only meaning 
associated with a particular lock number is that agreed upon by the 
group of cooperating file users. The following function provides an 
example of users cooperating in sharing a file. This function can be 
executed by several users simultaneously. It controls access to the 
file by locking individual records of the file while they are being 
accessed by file users. A lock-number specification here refers to a 
file record number. 

V H V. M I"- <■• C M r- H U M F" C.^ I-I A H J C M I-' 

L 1 1 ■■> ( /■ U '^=' ^'^ '•* '■■"■ '■•' f'^ '■■* V '■'" '"' '"■ ^"^ * ■' '"' ) / '•■■ '■ ' '■* '"' ^-^ •'■ '■• 

I," 2 ..i *■'■"■ ^ '"' <■• H C *■■ M •"■ f ■< *■' M "I V. I-I (■> H 

i: 3 1 ■> ( ^- u I--' ^- <•* '•• '■•' f'^ '■' !'())/ ''■'■' ^^- <•* •■■■ <'^ •': ' - 

II 4 1 '■< <•• ^ I"'' *■■ '"■ '"• *•' <■■ '=" ■"' ■•* '■" ^ '"■ 

II ^i II ^' <" ^ '•■■ <•• '■' <- ^ '"■ 13 II '^'^ ^ '■■■ '"^ *•■' ^ II *■• '■■' ^-^ '■' 

II 6 ;] -K !^ 1:' I-:: <s <- i-i a h ) / if i;:: <:* ("■ a x. i... 

II 7 II K) 
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: e ::i k: n c* i=" a .i: i... * ' III- ii (s I" A :i: i._ e x:i ■ g s :i: g h a i... 5 j 
: 9 :] 1" E a !"■ A :i: I... ♦ ' ti B (s I-" fit X I... Ill: xn • g s x c-, tt f^, 1... '5 2 

V 



Q F Q fit S S ' F A T' R O L. I... ^ F" Ei: E< / XH C^ / S l-l f^ R IL" ' 

.1.2 



7.8.3 Specifying a Share Bit 

The third argument in the UENQ and UDEQ system function, the share 
bit, can be specified if you are willing to share access to a lock. 
If the share bit is set to 1, sharing of a lock is established; if it 
is set to 0, you have exclusive use of the lock. The default share 
bit is 0. If several users specify a share bit 1 in an UENQ function, 
it is possible for all of the UENQs to succeed at the same time. Only 
one user can have exclusive access to a lock at any one time. 

The following example illustrates the interaction of four users access- 
ing the same file. The chronology of the functions issued and executed 
is shown in the time component. Note that requests are queued in a 
first-in-first-out fashion. 

Time User 1 User 2 User 3 User 4 

12:00. . .UENQ 12 10 

12:00. . .obtains 

exclusive 
access 

12:02 UENQ 12 1 1 

12:04 waits UENQ 12 1 1 

12:06 waits UENQ 12 1 

12 : 08 waits 

12:10 

12:12 UDEQ 12 1 obtains obtains 

shared access shared access 

12:14 UDEQ 12 1 

12:16. . .UENQ 12 1 1 UDEQ 12 1 obtains 

waits exclusive 

access 

12:18... obtains UDEQ 121 

exclusive 
access 
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7.9 ) INPUT AND ) OUTPUT HANDLING I/O FROM NON-TERMINAL DEVICES 



Format 



) INPUT |[f ilespecj] 

) OUTPUT^f ilespec 



/character setjj 
/character set]] 



I 



The ) INPUT and ) OUTPUT system commands allow you to divert immediate 
mode and quad I/O to devices other than your terminal. A file speci- 
fication can be included in the command to indicate the device and 
filename to be used for input or output. The file specification has 
the same format as a workspace name, and, as with a workspace name, 
you need not include all five parts of the file specification. See 
Section 2.1.4. When you omit parts of the name, the default values 
in Table 7-8 are assumed. If you omit the file specification, APL 
defaults to the terminal. 



Table 7-8 
File Specification Defaults 



Component 


Default 


Device name 


DSK: 


Filename 


Input for ) INPUT 




Output for ) OUTPUT 


File extension or type 


.AAS 


File protection 


Installation dependent 


File owner ID 


User's directory 



You can specify an optional parameter (the character-set switch) to be 
used in handling the data being read or written. Legal values are 
/APL for the APL character set and /TTI for the TTY character set. 
The default is the character set of the user's terminal. 

For TTY terminals, /APL means use the APL character set specified when 
you first accessed APL. When APL prompts with TERMINAL .. , you have 
the option of specifying a particular APL terminal, for example, 
TTY/4 013. The default is LA36. See Table 1-1. 

) INPUT and ) OUTPUT are typically used to divert input and output 
requests to devices other than the terminal. 

For example: 

■t OUT PUT I... FT ; 



7-40 



THE FILE SYSTEM 



This response intercepts all output normally directed to the terminal 
and routes it instead to the line printer. For example: 

) OUTPUT )t:iSI< J API... 



This command causes all normal terminal input requests to come from a 
disk file named AFL.AAS. 

If you use an ) OUTPUT command to divert output from the terminal, 
input is echoed to the output file as well, so that the output file 
has the appearance of a normal terminal sheet. This alleviates the 
potential confusion involved in trying to match up input and output 
requests. Special processing is also performed to help you synchro- 
nize input and output in the following two cases: 

1 . input from the terminal and output to another device 

2 . input from another device and output to the terminal 

In the first case, APL displays the usual six spaces at the terminal 
to signal the completion of the last output request. In the second 
case, the names of the functions whose definitions appear in the input 
file are listed on the terminal upon successful closing of the 
function. 

If errors occur in a function definition, the number of errors en- 
countered is displayed along with the function name. If the APL 
system encounters an I/O error when ) INPUT and ) OUTPUT commands have 
diverted both input and output from the terminal, I/O in the direction 
of the error reverts to the terminal. For example, if an error occurs 
on input, subsequent input is directed to the terminal, but output con- 
tinues to be sent to the output device. 
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If an error is detected during the evaluation of an expression, APL 
(1) displays an appropriate error message from the list included below 
and (2) the line in which the error occurred. A null array with the 
shape ERROR NUMBER is returned as the value of the expression that 
produced the error when executed with e . The following example of a 
null array indicates an end-of-file error condition: 





A + Xvf 


:l. :l 


VALUE ERROR 




AlXvt 




A 




Ci-ii > AfB ' 


:ll 


il VAI...UE ERROR 




A.jXvc 




A 




fC 


:l.:i 





The meaning of error-number values is summarized below. 

Error 

Number Meaning/Explanation/Action 

IMPROPER LIBRARY REFERENCE 

Attempt to ) SAVE a disk area that is not your own and not 
a public library area. 

1 WS NOT. FOUND 

No workspace or file with the name found in the disk area 
specified. 

2 SYSTEM ERROR 

Internal APL system error. Please report this error to 
your software specialist. 

3 WS FULL 

The active workspace cannot retain all the information 
requested, nor can it expand further. Erase unneeded 
objects, issue a ) MAXCORE command to enlarge the workspace, 
or do a )SAVE, ) CLEAR and ) COPY sequence on the needed 
information. 

4 NOT A VALID SV IDENTIFIER 

Attempt to use a shared variable not supported by this APL 
implementation . 
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Error 

Number Meaning/Explanation/Action 

5 DEFN ERROR 

Improper function definition syntax (function name may have 
been defined elsewhere) or improper edit request syntax. 
Function may be locked. 

6 LABEL ERROR 

Improper use of a colon or improper variable name. 

7 SYNTAX ERROR 

Invalid syntax, such as two variables without an interven- 
ing operator, a function call with missing arguments, or 
an unmatched parenthesis. 

8 INDEX ERROR 

Index value out of range, for example trying to reference 
the tenth item of a 9-element vector. 

9 RANK ERROR 

Ranks of two operands are not conformable. 

10 LENGTH ERROR 

Shapes of two operands are not conformable. 

11 VALUE ERROR 

Value for the variable in question has not been previously 
specified, or a function with an explicit result did not 
return a value. 

12 RANGE ERROR 

Value of result exceeds capacity of machine word. 

13 POSSIBLE SI DAMAGE 

A function in the state indicator has been erased or edited. 

14 DEPTH ERROR 

Too many right brackets or parentheses on a line. 

15 DOMAIN ERROR 

Function not defined for given values of arguments. 

16 UNBALANCED DELIMITER 

Execute string does not contain a closing quote or, function 
definition does not contain a closing 'del' character. 

17 EDIT ERROR 

Improper line editing request. 

18 ATTENTION SIGNALED 

Attention signal detected during function execution (not 
all attention signals produce this message) . Attention is 
signaled on ASCII terminals by two CTRL/C characters and 
by the ATTN key on 2741-style terminals. 

19 DEVICE DOES NOT EXIST 
Improper device specification. 

20 DEVICE NOT AVAILABLE 

The desired device is already assigned to another job. 
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Error 

Number Meaning/Explanation/Action 

21 INCORRECT COMMAND 

A system command is incorrectly spelled. 

22 INCORRECT PARAMETER 

Improper command syntax for a recognized system command. 

23 WS LOCKED 

An improper password (or none at all) has been given to 
access a workspace with a )LOAD, )COPY, etc., command. 

24 NOT GROUPED, NAME IN USE 

The group-name specified has been defined elsewhere. The 
objects in the group-member-list have not been grouped. 

25 EXECUTE ERROR 

31 PROTECTION FAILURE 

Attempt to ) LOAD or ) SAVE a read-protected workspace from 
disk area other than your own, or a directory is full. 

32 FILE BEING MODIFIED 

Two users are trying to ) SAVE the same workspace simulta- 
neously, or a file is already in use (by another user) 
during direct-access file I/O. 

33 UNEXPECTED FILE ERROR 

35 DIRECT I/O ERROR 

An error has occurred during a directory read or write. 

39 NO SUCH DIRECTORY 

41 NO ROOM ON THIS FILE STRUCTURE OR QUOTA EXCEEDED 

File structure is full or disk allocation is exceeded. In 
the latter case, files must be deleted from the user's disk 
area before more files can be added. 

4 2 WRITE-LOCK ERROR 

Device is physically write-protected (usually a magnetic 
tape) . Write-enable the device. 

43 NOT ENOUGH TABLE SPACE IN MONITOR 

The system has run out of space to perform certain functions 
for the user. See the systems programmer at your install- 
ation. 

44 PARTIAL ALLOCATION ONLY 

Entire space request for a disk file allocation could not 
be fulfilled. The space that was available has been 
allocated. 

4 5 BLOCK NOT FREE ON ALLOCATED POSITION 

A disk block that the monitor allocated to APL as free is 
not available. See the systems programmer at your install- 
ation. 

4 6 MESSAGE TOO LONG 

The maximum message length for the HI message has been 
exceeded. Maximum length is 384 characters. 
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Error 

Number Meaning/Explanation/Action 

47 LINE TOO LONG TO EDIT 

Line editing is not permitted on multiple-line statements 
(such as statements that overflow to the following line or 
multiple-line quoted strings) . It is sometimes possible 
to edit the line by changing the ) WIDTH parameter, to set 
the whole statement on one single line. 

48 INPUT LINE TOO LONG 

4 9 FILE CONTAINS A DAMAGED WS 

50 ERROR IN GARBAGE COLLECTION 

Internal APL system error. Please report this error to 
your software specialist. Workspace damage is probable. 

51 ERROR IN COPY 

An error has occurred during a ) COPY command. Please re- 
port this error to your software specialist. Workspace 
damage is probable. 

52 LINKAGE ERROR 

Internal APL error. Workspace damage has been detected. 
Please report this error to your software specialist. 

53 NOT ENOUGH CORE AVAILABLE 

Not enough memory is available for the task requested. This 
error results when the user is within the limit specified 
by the ) MAXCORE command, but the system itself does not 
have enough memory to allow the workspace to expand. Re- 
vise your needs for memory, use virtual storage facilities, 
or try to run at a time when more memory is available. 

54 STACK OVERFLOW 

Internal APL error. There is not enough room on the stack 
for APL operations to continue. Please report this error 
to your software specialist. Workspace damage is probable. 

55 LOGICAL NAME DSK DOES NOT REFER TO PHYSICAL DISK 

APL has determined that the logical name DSK does not refer 
to a physical disk structure. Reassign the name DSK to a 
disk (necessary for direct access I/O) . 

56 INCORRECT MODE FOR DEVICE 

The I/O mode for the action requested is improper for the 
chosen device (e.g., trying to ) SAVE to a terminal). 

57 FILE DOES NOT CONTAIN A WORKSPACE 

Attempt to ) LOAD or ) COPY a file that does not contain an 
APL workspace. 

58 I/O ERROR 

A data-transmission error was detected during input or 
output. This message is usually associated with a non- 
recoverable device error. 

59 FILE ALREADY EXISTS WITH GIVEN NAME 

Attempt to )SAVE a workspace with the same filename as an 
existing file that is not a workspace. Either rename the 
existing file on disk or change the ) WSID of the APL 
workspace. 
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Error 

Number Meaning/Explanation/Action 

6 WS NOT SAVED, THIS WS IS 

Attempt to ) SAVE a workspace with the same filename as an 
existing workspace, without specifying the )WSID first. 
This error message is to prevent inadvertent overwriting 
of previously saved workspace. 

61 RENAME ERROR 

An error has occurred during file deletion or protection 
alteration. This frequently occurs when a file or work- 
space is already protected and cannot be renamed. 

62 NOT A PROPER DEVICE 

Improper device selection, for example trying a ) SAVE to a 
device which supports dump-mode I/O but which is not a DSK. 

64 CHANNEL NOT ASSIGNED 

The channel specified in a file operation has not been 
previously associated with a file via a BASS system 
function. 

65 CANNOT DO BOTH INPUT AND OUTPUT 

Either input or output, but not a combination of both, is 
allowed to a sequential file. Close the file and reopen 
it to perform the desired operation. 

66 CANNOT INPUT FROM FILE 

The user has tried to input from an output-only device, 
such as a line printer. 

67 CANNOT OUTPUT TO FILE 

The user has attempted to output to an input-only device, 
such as a card reader. 

68 FILE LOCKED 

An improper password has been given for a direct-access 
file. 

69 FILE FORMAT NOT DIRECT ACCESS 

An attempt has been made to perform direct-access I/O to a 
non-direct access file. 

7 FILE FORMAT NOT INTERNAL SEQUENTIAL 

An attempt has been made to perform internal sequential I/O 
to an non-internal sequential access file. 

71 IMPROPER MODE OR SOFTWARE CHECKSUM ERROR 

A file operation is attempting to use a mode that is im- 
proper for the device specified in an UASS system function. 
Issue an UASS to a device that supports the necessary mode. 

72 DEVICE ERROR 

Physical device error during file I/O. Report this error 
to your operations staff. 

7 3 DEVICE DATA ERROR 

A checksum or parity error during file I/O has occurred. 
The file is possibly recorded incorrectly on the specified 
device . 
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Error 

Niamber Meaning/Explanation/Action 

74 BLOCK TOO BIG 

A data-transfer error has occurred during I/O. Specifi- 
cally, the last user has attempted to read a block of data 
that is too large. 

75 

End-of-file (EOF) detected (no message is printed; 
execution continues) . 

7 8 END OF TAPE 

End-of-reel on a magnetic tape (MTA) detected. 

79 SYSTEM FUNCTION ILLEGAL IN EXECUTE OR IMMEDIATE MODE 
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This appendix contains the following items in the form of tables 



Primitive Scalar Functions 

The Dyadic Circle Function 

Relational and Logical Functions 

Primitive Mixed Functions 

Extended Functions 

Operators 

System Variables 

System Functions 

Keyboard I/O Functions 

File I/O Functions 

System Commands 



Table B-1 
Table B-2 
Table B-3 
Table B-4 
Table B-5 
Table B-6 
Table B-7 
Table B-8 
Table B-9 
Table B-10 
Table B-11 
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SUMMARY 



Table B-1 

Primitive Scalar Functions 

(Section 3.2) 





Monadic 


Dyad 


ic 


Function 


Meaning 


Function 


Meaning 


+ Y 


Y 


Z + Y 


Add Z to Y 


~Y 


Negative of Y 


X-Y 


Subtract Y from X 


xY 


Sign of Y^ 


JxY 


Multiply X and Y 


vj 


Reciprocal of Y 


JtY 


Divide X by Y 


*Y 


£ to the Yth power 


Z*Y 


X to the Yth power 


\Y 


Magnitude of Y 


J| Y 


X residue of Y 


FY 


Ceiling of Y 


XlY 


Maximum of X and Y 


LY 


Floor of Y 


XlY 


Minimum of X and Y 


®Y 


Natural logarithm of Y 


X®Y 


Log of Y to the 
base X 


!Y 


Factorial of Y 


XlY 


Binomial 
coefficient 
(number of com- 
binations of Y 
things taken X at 
a time) 


?Y 


A random integer of \Y 


X?Y 


X number of random 
integers in the 
range 1 through Y 


OY 


Pi times Y 


XoY 


Trigonometric 
operators (Y is in 
radians. See 
Table B-2.) 



^Definition: xY is -1 if Y<0 
xY is if Y=0 
xY is 1 if Y>0 
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Table B-2 
The Dyadic Circle Function 



Expression 


Result 


Expression 


Result 


OCX 


(1-J*2)*. 5 






lOZ 


sine X 


-loj 


arcsin X 


20Z 


cosine X 


-20J 


arccos Z 


30J 


tangent X 


-30Z 


arctan X 


40Z 


(1+J*2)*.5 


-40Z 


(-1+Z*2)*.5 


50J 


sinh X 


-50Z 


arcsinh Z 


60X 


cosh Z 


-50J 


arccosh Z 


loX 


tanh X 


-70J 


arctanh Z 



The functions in Table B-3 return 1 if the relationship is true, and 
if it is false. 



Table B-3 
Relational and Logical Functions 
(Sections 3.2.1 and 3.2.2) 



Function 




Meaning 


X<Y 


Z 


less than Y 


X<Y 


Z 


less than or equal to Y 


X = Y 


Z 


equal to Y 


X>Y 


X 


greater than or equal to Y 


X>Y 


X 


greater than Y 


X^Y 


X 


not equal to Y 


ZaY 


X 


and Y 


zvy 


X 


or Y 


X^Y 


X 


nand Y (not both Z and Y) 


X>^Y 


neither Z nor Y 


~J 


not Y 
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Table B-4 
Primitive Mixed Functions 



Function 


Section 


Meaning 


X,Y 


3 


3 


.1 


Catenate J to 7 along the last dimension 
of X 


X/Y 


3 


3 


.2 


X (logical) compression along the last 
dimension of Y 


X/IN']Y 


3 


3 


.2 


X (logical) compression along the ^th 
dimension of Y 


XiY 


3 


3 


2 


X (logical) compression along the first 
dimension of Y 


X?Y 


3 


3 


3 


Deal X integers selected randomly in 
range 1 through Y without duplication 


XlY 


3 


3 


4 


Decode the representation of Y in number 
system X 


X-^Y 


3 


3 


5 


For X>Q , drop first X elements of J - for 
J<0, drop last \X elements of Y 


XjY 


3 


3 


6 


Encode Y in number system X 


X\Y 


3 


3 


7 


X (logical) expansion along the last 
dimension Y 


XMN^Y 


3 


3 


.7 


X (logical) expansion along the il^th 
dimension of Y 


X\Y 


3 


3 


.7 


X (logical) expansion along the first 
dimension of Y 


XllY 


3 


3 


8 


Generate an index vector such that 
JCfJ] is in descending order 


XkY 


3 


3 


.9 


Generate an index vector such that 
Xll^Y^ is in ascending order 
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Table B-4 (Cont.) 
Primitive Mixed Functions 



Function 


Section 


Meaning 


xY 


3.3.10 


Generate the first Y consecutive integers 
from current origin 


XxY 


3.3.11 


Find the first occurrence of Y in vector 

X 


x,\:niy 


3.3.12 


Laminate Z to Y along the ^th dimension 
of X 


XeY 


3.3.13 


Determine the membership of X in array Y 


>Y 


3.3.14 


Return the ravel of Y (make Y a vector) 


<t>Y 


3.3.16 


Reverse along the last dimension of Y 


HN2Y 


3.3.16 


Reverse along the iVth dimension of Y 


ej 


3.3.16 


Reverse along the first dimension of Y 


P^ 


3.3.18 


Return the shape of X 


XpY 


3.3.15 


Reshape J to make dimension X 


X<^Y 


3.3.17 


Rotate by X along the last dimension of Y 


x(^ln:iy 


3.3.17 


Rotate by X along the Nth dimension of Y 


XeY 


3.3.17 


Rotate by X along the first dimension of 

Y 


X'\-Y 


3.3.19 


For X>0, take first X elements of 7 - for 
X<0, take last \X elements of Y 


is?J 


3,3.20 


Transpose the dimensions of Y (for a 
matrix, exchange the rows and columns) 


Xls^Y 


3.3.21 


Transpose array Y according to X 
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Table B-5 
Extended Functions 



Function Section Meaning 

iY 3.4.1 Invert the matrix Y 

XWY 3.4.2 Perforin matrix division, solve linear 

equations, find a least squares solution 

eY 3.4.3 Execute the character string Y 

lY 3.4.3 Execute the character string Y 

lY 3.4.4 Execute the character string 7 

X$Y 3.4.5 Format data (see below) 

tY 3.4.6 Format character array Y 

X-vY 3.4.7 Format character array Y with width and 

precision specified by X 



tY 3.4.8 For numeric Y, convert to a character 

string - for character string Y, if Y is 
not a variable or function name, return 
the null vector; if Y is a variable to a 
character string; if Y is a function to a 
character string consisting of the lines 
of Y separated by a carriage return/line 
feed 
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In the following table, f and g stand for any primitive scalar dyadic 
function. 



Table B-6 
Operators 



Operator 


Section 




Meaning 


Xf.gY 


3.5.1 


Inner 


product 


XofY 


3.5.2 


Outer 


product 


f/Y 


3.5.3 


The f 
of Y 


reduction along the last dimension 


f/LNlY 


3.5.3 


The f 
of Y 


reduction along the Nth dimension 


f/Y 


3.5.3 


The f 


reduction along the first 






dimension of Y 


f\Y 


3.5.4 


The f 


scan along the last dimension of Y 


f\LNlY 


3.5.4 


The f 


scan along the Nth dimension of Y 


f\Y 


3.5.4 


The f 

Y 


scan along the first dimension of 



The format function is used with the following syntax: 



or 



FMT $ V',V2i . . .VN 
FMT $ V 



where 



V can be any variable or expression 

FMT must be a character vector containing one or more format 
fields chosen from the following list: 



Format 

'MAI7' 

'MQFW.D' 
'MQIW^ 

'MHtextH' 



Meaning 

Character data; cannot be used with 
numeric values 

Floating-point numeric data with 
exponent 

Fixed-point numeric data 

Integer numeric data with automatic 
rounding 

Blanks inserted in edited line 

Literal text inserted in edited line 
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where 



M is the optional repetition factor. 

W is the field width. 

D is the number of decimal positions. 

Q is any number of qualifiers chosen from the following list: 

Qualifier Meaning 

B Blank field if value is 

C Insert commas 

L Left-justify 

Z Zero-fill 

Mffltextn Insert text left of negative result 

NHtextffl Insert text right of negative result 

PHtextC] Insert text left of nonnegative result 

QEtextH Insert text right of nonnegative 
result 

RHtextZ] Insert text in background 

You must separate format fields with commas. Up to eight signi- 
ficant digits can be specified. 

The symbol pi can be used instead of H (" for TTY terminals). 
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Table B-7 
System Variables 



Variable 


Section 


Meaning 


Can be reset: 










UAUS 


4 


.2 


.5 


Automatically backs up the active 
workspace if value is 1 . 


UCT 


4 


.2 


.7 


Sets the degree of tolerance or relative 
fuzz to be applied in performing 
comparisons, value must be in exponent 
form; range through IE 8. 


UERROR 


4 


.2 


.9 


Contains three lines describing the error 
that occurred. 


UGAG 


4 


.2 


.10 


Inhibits messages sent from other users. 


UIO 


4 


.2 


.11 


Changes the setting of the index origin 
to or 1 . 


ULX 


4 


.2 


.13 


Defines an expression to be executed 
automatically when the workspace is 
activated. 


DPP 


4 


.2 


.15 


Sets the precision of non-integer output. 
Legal values are integers in range 1 
through 1 8 . 


UPW 


4 


2 


16 


Sets the maximum number of characters 
that can appear in an output line. Legal 
values are integers in range 3 through 

390. 


URL 


4 


2. 


17 


Determines a link in the chain of random 
numbers used in the roll and deal 
functions. 


USF 


4. 


2. 


18 


Sets a new prompt or signal message for 
evaluated input. 


UTIMELIMIT 


4. 


2. 


19 


Sets a limit to the amount of time you 
have to respond to a quote-quad input 
request. 


UTBAP, 


4. 


2. 


21 


Expression to execute when an error 
occurs within a user-defined function. 
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Table B-7 (Cont.) 
System Variables 



Variable 


Section 


Meaning 


Retain system 


-specified 


values: 


UAI 


4 


.2 


1 


Stores account information on the current 
APL session, including user identifi- 
cation and CPU connect, and keying time. 


UALPEA 


4 


.2 


.2 


Contains a vector of 2 7 characters A and 
A through Z . 


UALPHAU 


4 


.2 


3 


Contains a vector of 2 7 underlined 
characters A and A through Z. 


UASCII 


4 


.2 


4 


Contains 128 ASCII characters. 


UAV 


4 


.2 


6 


Contains a vector of every character in 
APL. 


UCTRL 


4 


.2 


8 


Contains a vector of 32 characters listed 
in Table 4-3. 


DLC 


4 


2 


12 


Stores a vector of line numbers in the 
APL workspace state indicator, arranged 
in order of most recently suspended 
function first. 


UNUM 


4 


.2 


14 


Contains a vector of the 10 digits , 1 , 

2, 3, 4, 5, 6, 7, 8, 9. 


UTIMEOUT 


4 


2. 


20 


Reports whether a user ran out of time 
during a quote-quad input request. 


UTS 


4 


2 


22 


Stores the current data and time in base 
format. 


UTT 


4 


2. 


23 


Determines the time of terminal being 
used in current session. 


UUL 


4 


2. 


24 


Stores the system job number associated 
with the current APL session in base 10 
format. 


UWA 


4 


2. 


25 


Determines the maximum amount that the 
active workspace can increase. 
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Table B-8 
System Functions 



Function 


Section 


Meaning 


UBREAK 


4 


3 


1 


Suspends function execution and returns 
you to immediate mode. 


UCR 


4 


.3 


.2 


Obtains a canonical representation of a 
defined function whose name is the 
character string you specify. The 
function lines are reformatted to be of 
equal length, thus allowing the result- 
ing function to be treated as data. 


UBL 


4 


.3 


.3 


Delays the execution of the function in 
which it is included by the number of 
seconds specified. 


UEX 


4 


.3 


.4 


Erases an existing use of a name in the 
workspace. It will not erase a label, a 
group, a suspended or pendent function, 
or a system variable. 


UFI 


4 


.3 


5 


Takes a character argument and converts 
it to a numeric, placing zeroes in each 
position that does not correspond to a 
valid number. 


UFX 


4 


3 


6 


Reverses the operation of the DCR system 
function. 


UNC 


4 


.3 


.7 


Returns the classification of a name or 
list of names. 


UVIL 


4 


.3 


.8 


Constructs a list of named objects 
residing in the active workspace. 


UQLD 


4 


.3 


.9 


Loads a workspace. 


UQCO 


4 


.3 


.9 


Copies a workspace. 


UQPC 


4 


.3 


.9 


Copies a workspace with certain 
protection. 


QSIGNAL 


4 


.3 


.10 


Signals an error up the stack one level 
to the caller. 


UVI 


4 


.3 


.11 


Converts a character vector into a 
numeric vector. 
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Table B-9 
Pile .Systetji' Functions 



function ■' ^•'\,:- Meaniiig ' !,.^;;{C - >i;f' -'f^ Section 

■ • ""'«- " ' — • '■ ' ■ "' mi ' '" . '.M . . . ■■ ' ' ■ » ■ ' •<• " ' ■ ' iii ' ' m . Mf. i ' ;., ! ,» . : .. . ■ i ja/j i M iii . , . ~w i , i i/ , W i|, - , : , , 

0;at^nAPPENp vdhann^l' -I, header ■'!,%£© [^ft«p:^ J ^''-'r^-''^''^^'' 7.6.3 

\ Allws' you to''writ^"':af-tery the' eii<5^0-f- 7.6.6 

DXJ^jS 'channel fijespeo |passwori||l/filebrg||^^ ' 7.4.1 

■:i#«J^? -'^^lAi'p :ft-||^§$ .and, etfectM^^T-c'^PJ^f:'''^'^^7-^^M^^^^^ 

■ '■-. '" injpfUt' dr output,' -", '■'■' '' '" ■':•••■'•'[' "• ' ";'i^--'^f'v'-^ ■""';;^% 

acff5 channel ,(s) ^y;,,_ ;:■, . >; ■■ , ■ .=uh^.;. , -J/^-,, ]:ri 7.7.1 

}','/\;\- BJ&tii3^;'the';fii^":oi?fah4?;?!,ji^ ■■■•v^« 
'y r Open'- status./ of -the riie^'''pn' one\"<3|r^;3^ 

channels. "■■ ' ^/-^ '''''-'M':- ■'■.'':(-• 

UCIQ |header|,t^Jl.| . ,. ■. ■■'.: \ ■ ■:;}\:. .:' ^':M''-S'h-0M:fkiMm 

. UiTii^l^TS-; data accxmuXate&^ipr. ^Bt^a^^- 
with-WOQ , \ ■ ■ ' '■'::';'./' ■■'■' ' ~' '/"'■'Ji-'-'' '^'^i!':'' " 

nC£^ chanjrieKs).,,!; ,\:/ ■' '■' . ■ .^ --Xt": , ;':Vffc;,.,,-':?^ft.3 

;■ ^■'■■- .;y <iio$e^-the f iles ,on, pne^ pr. mora cha|W:^ls^»^f^9i=5a^ 

data DC'^^>^|IheadBi^;.|/typeJJ ' . '^'y''' ' ''■^€I5^-^-''^'^?||Sj*'^' ' 

, ■'■("";:■■■ PacHs; data of different types intq/'^/ 'Hl^/;^; '.'ffSi 
'■KJH.' ■>■■' '■• "\ ^^^^^^-^^ ^^^ storage'^as one"' logical/; '■ ■'-' . t^^TC';-'-^;V;f^:Jv;^;i;; 

ODA^ chann^iCs)"^^. ' ' ,^ . 'j';;;" /."v ■^^§^• '"'^|4.2 

■\;. ■ Deassigns the' files' on one'^br inor;e:;' /''%s ,^':l'$" 

.' 'r-;i- cha|i|je.ls. ^;^v.; '- - ..^;^/: ■',.';■ .:., ^■, '■ ,, ■ \ ;;^■.^'v.:.-■■'■'iftx;yai/€^■;&A^^ 

UDEQ channel' Icfek 'number ' - ■-■^■■".■■■^ • , ,^^,.: ■•■ •>:=,:,,;;;: ■•••/,}4fj|;;;- '',';^|;^''' ' 

' ■?• Synchronizes shared acce^^"ji:o muXl;iip.e~ ^ ;;?;r5;,/ ':'0(:t 
,;,,..-,.- -■ ,,^j4,/;,--.tts^ 'files -by releasing tBe^^'4ock4^'vf|x^^^-^^|^^;^;.^^^ 

cft§ chaiSei(s) — ' " '"„ ' : ' ' ■ ■- • '■', ■'"; '-'-7'' -^ '"-SJI^iMiSS^ 

■> ";■ ' '"'■■ ".;•' Returns device characteristics woi^d and '■■■■-(^ir::' "' "'rii:-:'-" ' 
[:„'"; ';,;;, blocksize for one -or more files, /-'/az,, ,;5J;U, .^^=)(;, 

^C^te ' d^^gf&:^l.,'fJ^fe ■m«ii^fe--:-:shife,,bit - •,,,;■; .>. :;;;\^?J-5;#5l x^S'S^l^^fSJ^K 
''"'■•■■' ' ';'■ .i?.-":*''"Syn§hi:oni-»^i;''shar^^ 
; , -. j-y:- us€ir';;files ,by issuing • a request i^^^^qn&^fff,^ /S$fl 

'• ••' "'''r'-"':-. on''a:vlock pair. , ,, '■-" , '■■■■''■■■■■■.'. •\:J'::t''-''- - ^y^^tff^ii■'>■■^'cS•0:^■r.■■ 
' 0i^M -ahaxi^el '",' " . ' " - ":^' ■■ ..■ '■■■ '- I'v- :'''-■''-■' ■':--^^^ 

r;_';v,' Retiiirns information /about;' 'tjie recoM's in:^|5l/^''''' ''''~5>t§*'-"' '^ 
•'■-."■' a dirfect-access file^,. '■•''':'■"■ 'S^i':, '."Hfl;, .-l*^ 

']^'ltB chrnm^'. -x'-j^^SC' ./ i ,,• , \ , '-■^~'-~-?^^'TVf;^-C^ISii^3^^^^?^K^^^^ 

"'':, " 'J :''> Ret@ds- the'',sh^ringv status:^:|t^ 

j"';' inif!6rtaatioh=' .about-, files on;>!one or:=)itore '-^l-' '-i^-,' 

''■,. -' , chanhels. ,.'.''' "''.•■'^'; :"•''':'■■'.. . ':'■%■■ ■^~-si?'=^/, .■ -it'sS 
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Table B-9 (Cont.) 
File System Functions 



Function 



Meaning 



Section 



channel DA/TP operations 7.6.8.2 

Performs a variety of magnetic tape 
operations including rewinding, setting 
density, and returning data mode. 

'tiles^ec'UBE NAME channel 7.4,4 

Renames a currently assigned file. 



File System Arguments 



Argument 
channel 

data 
filename 



file org 



Meaning 

An integer in range 1 to 12 inclusive specify- 
ing the channel on which the file being 

referenced is assigned. 

The value to be input or output by the I/O 
function. 

A standard filename in the following format: 

device : name . extension<protection> [directory] 

All fields except the name itself are optional. 
If you include the protection, enclose it in 
angle brackets. If you include the directory 
enclose it in square brackets. Names are a 
maximum of six letters and/or numbers. An 
extension consists of a period or comma followed 
by a maximum of three letters and/or numbers. 
Defaults are the following: 



Component 

device 

name 

extension 

(file type) 
protection 
user ID 

One of the following: 

Switch Default Ext 



Meaning 

DSX: 

No default 

File-org dependent 

Installation-dependent 
User's directory 



/A3 

/AS* 

/IS 

/1 3* 



,AAS 
.AAO 

,AIS 
.AIC 



Meaning 

ASCII sequential 

ASCII sequential; opened 
for append 

Internal sequential 

Internal sequential; 
opened for append 
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Table B-9 (Cont.) 
File System Functions 



Argument 

file org 
(cont. ) 



header 



length 
lock-number 

operations 

password 
share bit 

type 



File System Arguments 



Meaning 



Switch 

/DA 

/DI 

IBS 
/BS* 

/BU 



Default Ext 

.ADA 

,ADA 

.ABI 
.ABI 

.ABI 



Meaning 



Direct-access; read and 
write 

Direct-access; read only 
(default) 

Binary-access; read or write 

Binary-access; opened for 
append 

Binary-access; read and 
write; one user at a time 



A specification indicating whether or not a 
header is included to indicate the type and 
number of values in the input or output; 1 is 
the default and indicates a header; indicates 
no header. 

The number of characters or digits to be written 
in one operation. 

A number in range through 2*3 3-1 used to 
synchronize shared file access by multiple 
users. 

A vector containing codes indicating particular 
magnetic tape operations; identical to the 
meaning of codes used by the TAPOP UUO on 
TOPS-10. 

Up to eight characters preceded by a hyphen (-) . 
The null and default password is the hyphen. 

A specification indicating whether or not a user 
is willing to share access to a lock on a file; 
1 indicates that sharing is desired; is the 
default and indicates exclusive use of the lock. 

Type of value to be input or output; one of the 
following : 



Value 

1 

2 

-i 

4 
5 
6 



Type 

Integer 

Boolean 

Single-precision floating-point 

Double-precision floating-point 

APL 9-bit 

ASCII 
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Table B-10 
Keyboard I/O Functions 



Function 


Section 


Meaning 


X^U 


2.5.1 


Quad (evaluated) input from keyboard 


X^E 


2.5.2 


Quote-quad (character) input from 
keyboard, up to but not including 
carriage return 


Z^M 


2.5.3 


Quad-del (unedited) input from keyboard 


D^;^ 


2.5.5 


Quad output (display value of X) 



Table B-11 
File I/O Functions 



Function 



Section 



Meaning 



[mode] ) 
\ [record]/' 
'[word] / 



dataS {^[record J I 



Jj[word! 



channel 



channel 



7.3 
7.3 



File input 



File output (write 
value of data) 



The arguments in the file functions have the following meaning: 
channel 



data 

mode 

record 

word 



is the channel number (1-12) on which the file is 
assigned. 

is the information written to the file. 

mode of input or output (ASCII sequential 
file) . 

record is the record to bo read or written 
(direct-access file) . 

word is the word to be read or written 
(binary-access file) . 
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j§^f|ii|||;|lil§|f^ifli5;i^^ 



i^||^|p^|>f|-:;;g 


character Set 


IHMB 


iBiiliiiB 


TTY 


liilB 


■lIHPIiliBi 


TTY 


B^B 


Hsiiiiiiii 


TTY 


^^B 


BMiiiiiii 


APL 


^^B 


■iiiiii 


APL 


B^H 


IBililiilSiil 


APL 


1^8 



Table B-12 
System Commands 



Command 



Section 



Meaning 



)BLOT 



M 



)C 



[[nJJ file spec. 



)CALL Jn]] file spec 

) CHARGE 



) CLEAR 



) CONTINUE ^HOLD^ 



5.7.1 Generates a mask in a random 
pattern of length n for con- 
cealing confidential input. 
If n is not specified, the 
default length is 25. 

5.6.1 Ends current session after saving 
active workspace; returns you to 
operating system command level 
and runs program specified. The 
default device searched is SYS:. 

5.6.1 Same as )C except the default 
device searched is DSK: . 

5.7.2 Displays a record of activity 
during the current APL session. 
Information is installation- 
dependent, but includes connect 
time, CPU time, and the number 
of APL statements and operations 
executed. 

5.2.1 Replaces the active workspace 
with the clear workspace. 

5.6.2 Saves the currently active 
workspace as the continue 
workspace and exits from APL. 
Unless HOLD is specified, the job 
is logged off the system. On 
disk, the workspace appears with 
the name CONTIN .APL in your disk 
area. 
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Table B-12 (Cont.) 
System Commands 



Command 


Sect 


ion 


Meaning 


) COPY wsname 
[[password]] 
([named-ob ject-listj 


5 


.4 


.1 


Copies objects identified in 
the named-object-list from 
username into the current 
workspace. If the list is 
omitted, variables, functions 
and groups are copied. 


)cre:ai:e filesize 
[[filespec password]] 
[[blocking factor]] 


1 


, U 


.1 


Creates a direct-access file and 
associates a password, blocking 
factor, and number of records 
with the file. 


) DIGITS [Tn] 


5 


.5 


.1 


Displays or changes the number of 
significant digits displayed on 
output. The maximum number is 
18. The default is 10. 


)DROP wsname 
[[switchlist]] 


5 


2 


.2 


Deletes the workspace username 
from your disk area. Information 
specified by switch-list is dis- 
played as the files are deleted. 


\L\OFFfl 


5 


5 


.2 


Allows or suppresses the display 
of error lines. The default 
setting is ON. 


) ERASE name-list 


5. 


4 


2 


Erases the objects identified in 
name-list from the active 
workspace. 


)FNS letter 


5 


4 


3 


Displays an alphabetical list of 
function names in the current 
workspace. If letter is included, 
the list begins at the specified 
letter. 


) GROUP group-name 
[[group-number- list]] 


5. 


4 


4 


Collects named objects in the 
group-member- list into the groups 
specified by the group-name. If 
you omit the list, the group-name 
is dispersed. 


)GRP group-name 


5. 


4 


5 


Lists the members of the group 
identified by the group-name. 


) GRPS [[letter] 


5. 


4. 


6 


Displays an alphabetical list of 
group-names. If letter is in- 
cluded, the list begins at the 
specified letter. 
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Table B-12 (Cont.) 
System Commands 



Command 



Section 



Meaning 



)INPUT\ifile specll 7.9 

[[/character set]] 



)LIB wsname 5.2.3 

[[switch- list]] 



rr)LOAD -n 5.2.4 

[[magtape-position JJ 
wsname ([password 11 

)MAXCOREr[ iV-of-memory'iTi 5.3.1 
U. (K-of -memory fJJ 



li\K-of -memory j JJ 



)MODE [Tj KEYWORD \^"n 
III ESCAPE fJJ 



5.5.3 



)MON 



5.6.3 



)OFF ^HOLD^ 



5.6.4 



Specifies an alternate device and 
filename from which APL input is 
to be taken; if you omit the 
file spec, input is accepted from 
the terminal. The character set 
is either APL or TTY. 

Displays the names of workspaces. 
If you omit wsname, all workspaces 
in your disk area are listed. 
The switch-list argument controls 
the display of additional 
information about the workspaces. 

Retrieves a workspace from a 
secondary storage device. If you 
include a password, it must match 
the password of the file. 

Displays or changes the current 
setting for the maximum workspace 
size. The standard default is 
20K words on TOPS-10 and 40P 
words on TOPS-20 for the data 
segment. The maximum value for 
K-of-memory is the smaller of 
17 6K words or the system memory 
limit. For P-of -memory, the 
maximum value is 352P. 

Displays or changes the current 
setting for the minimum workspace 
size. The minimum and standard 
default on both systems is 0. 

Displays or changes the current 
mode of output for terminals that 
do not have an APL character set. 
The default is KEYWORD. The mode 
setting does not affect input 
from the keyboard and either mode 
is acceptable on input. 

Returns you to operating system 
command level, leaving your 
workspace intact. While at 
command level, you can issue any 
command that does not alter your 
memory image. You can subse- 
quently return to APL by typing 
the CONTINUE monitor command. 

Ends the current APL session. 
Unless you specify HOLD, your job 
is also logged off the system. 
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SUMMARY 



Table B-12 (Cont.) 
System Commands 



Command 



Section 



Meaning 



) ORIGIN f[n]| 



^OUTFUT^tilQ specj 
[T/character set]] 



) OWNER 



)PASSWORD [[password| 



)PCOPY wsname 

password]] 

hamed-object-list]] 



)R f[n]| file spec. 



)RUN f[n]] file spec 



)SAVE [[magtape 
posit ion]] [[wsname]) 
[[password^ 



5.5.4 Displays or changes the index 
origin for the currently active 
workspace. n can be or 1. The 
default setting is 1. The origin 
is preserved with the workspace 
when it is saved. 

7.9 Redirects terminal output to 

another device and filename. If 
you omit the filespec, output is 
sent to the terminal. The 
character set parameter is either 
APL or TTY. 

5.3.3 Displays the directory of the 
user who created the currently 
active workspace, the date on 
which it was created, and the 
terminal number of the device at 
which it was created. 

5.2.5 Displays or changes the password 
of the currently active 
workspace. 

5.4.7 Copies objects identified in the 
named-object-list from wsname 
to the current workspace, 
protecting names already in use. 
If you omit the list, all 
variables, functions, and groups 
are copied. 

5.6.5 Ends the current APL session and 
runs the specified program. If n 
is specified, the value is added 
to the starting address of the 
program to be run. The file 
specified must contain a ready- 
to-run program (that is, an .EXE 
file) . The default device 
searched is SYS:. 

5.6.5 Same as )R except that the 
default device searched is DSK: . 

5.2.6 Saves a copy of the currently 
active workspace on a secondary 
storage device, under the name 
and password specified. If you 
omit the password, the current 
password is assumed. If you omit 
both wsname and password, the 
current workspace is used 
OWSID) . 
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Table B-12 (Cont.) 
System Commands 



Command 


Section 


Meaning 


)SEALrf(ON )7 
U.\0FFJ1 


5 


3 


4 


Displays the current setting of 
the workspace seal or turns the 
seal on or off. When the seal is 
on, only the user who turned the 
seal on can copy objects from the 
workspace or can turn the seal 
off. The default is off. This 
command has no effect on the 
)LOAD command. 


)SI 


5 


4 


.8 


Displays the workspace state 
indicator which reports on the 
progress of function execution. 


)SIV 


5 


4 


.9 


Displays the workspace state 
indicator, along with local 
variable names at each level. 


)SIZE 


5 


3 


.5 


Displays the size of the currently 
active workspace, in P-of -memory on 
TOPS-20 and K-of-memory on TOPS-10. 
It also displays the number of 
pages (TOPS-20) or the number of 
blocks (TOPS-10) the workspace 
would occupy if saved on disk. 


)TABS ([n] 


5 


5 


5 


Displays or changes the increment 
between tab settings for APL 
output. The default tab setting 
is 0. This command is designed to 
be used with terminals that have 
physical tab stops. 


)TIME 


5 


3 


6 


Displays connect and CPU time 
accumulated while the current 
workspace has been active. 


)VARS [[letter 


5 


4 


10 


Displays an alphabetical list of 
global variables in the currently 
active workspace. If you include 
letter, the list begins at the 
specified letter. 


) VERSION 


5 


3 


7 


Displays the APL version number 
with which the currently active 
workspace was saved. 


) WIDTH [[ n ] 


5 


5 


6 


Displays or changes the maximum 
width of the output line; n must 
be an integer in the range 30 
through 390. 


)WSID [[wsname] 
[[password] 


5 


2 


7 


Displays or changes the name of 
the currently active workspace; 
optionally changes the password 
associated with the workspace but 
does not display it. 
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Argiiments 



Argument 
Blocking factor 

Character set 

filename 

file size 

file spec 
group-name 

group-member- 1 i s t 

identifier 

K-of-memory 

letter 
magtape-position 



Meaning 



name-list 



named-ob j ec t- list 



number 



password 



P-of -memory 



One of the following values: 8, 16, 32, 
64, or 128. The default is 16. 

The identifier APL or TTY, representing the 
character set of a user's terminal. 

Same format as wsname, except that the name 
itself has no default and the default 
extension depends on the type of file. 

An integer specifying the maximum number of 
records that a direct-access file can have. 

Same format as filename. 

An identifier that names a group of 
variables, functions, or other groups. 

A list of variables, functions, or 
group-names separated by spaces. 

Any sequence of letters or numbers 
beginning with a letter. Only the first 31 
characters in an identifier are 
significant. 

An integer value representing the number of 
IK-word blocks of memory. Users of virtual 
memory systems should note that IK is equal 
to two pages of memory. 

One of the characters A-Z^ A, or the 
understruck characters A-Z, or A. 

An integer that specifies that the action 
of the command is to take place following 
the nth end-of-file mark on the magnetic 
tape. If no position is specified, the 
action takes place with the tape in its 
current position. 

An integer value. 

A list of identifiers that name variables 
and/or functions, separated by spaces. 

A list of identifiers that name variables, 
functions, and/or groups, separated by 
spaces. 



One of the digits, 0, 1 

8, 9. 



2, 3 



7, 



Up to eight characters preceded by a hyphen 
(-) . The null and default password is the 
hyphen (-) . 

An integer value representing the number of 
pages of memory. 
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Argument 
switch-list 



wsname 



SUMMARY 



Arguments 

Meaning 

A list of switches in which each switch 
consists of a slash (/) followed by one of 
the letters A, B, C, L, M, N, F, or T. 
Valid switches include: 

/A Access: the date the file was last 
read (disk only) 



/B 
IC 



Blocks: the number of blocks required 
for the file 



Creation; 
file 



the creation date of the 



IL Long: equal to typing IB/VIC 

/M Mode: the mode in which the file was 
written (disk only) 

/N No header: suppresses the printing of 
the display header line 

/P Protection: the protection code 

associated with the file (disk only) 

/T Time: the creation time of the file 
(disk only) 

A standard name in the following format: 

device : name . extension<prot> [directory ] 

All fields are optional. If you specify a 
protection, also type the angle brackets. 
If you specify a directory, enclose it in 
square brackets. Names are a maximum of 
six letters and/or numbers. An extension 
(or filetype) consists of a period (or 
comma in TTY mode) followed by a maximum of 
three letters and/or numbers. Defaults are 
the following: 



Component 

device 

name 



Default 



DSK\ 



name of active workspace (from 

)WSId) 



extension .APL 

protection installation-dependent 

directory user's project-programmer number 
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APPENDIX C 
I-BEAMS 



I-beams are another aid for reporting statistics about the system. The 
following list shows the type of information returned by the 17 i-beams 
described in this section: 

1. Time of day or date 

2. CPU time, APL sign-on time, or keying time 

3. State indicator line numbers 

4. System job jumber of user's project-programmer number 

Some i-beams report on general system characteristics (for example, 
date) and others return information relevant only to a particular user 
and session (for example, number of APL operations performed). Some 
of the I-beams have the same functionality as the system variables 
and system functions described in Chapter 4 . This redundancy is pre- 
served in the current version of APL to promote the compatibility of 
APL programs written under previous versions of the language. However, 
where there are equivalent i-beams and system functions, we recommend 
that you use the system functions. 

An i-beam consists of the i character and an integer scalar. You type 
the I character by overprinting the encode character (t) with the 
decode character (i) . 

The following paragraphs list il7 through i33 along with the type of 
information they return: 

il7 Returning Symbol Table Information 

i::hx:i.7 

16 3 



The il7 returns information about the symbol table associated with 
your workspace. This i-beam returns a 2-element vector in which the 
first element is the symbol table size in words and the second is the 
number of symbol table entries in use in the workspace. 
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il8 Returning the Condition of the Workspace 

xJ.8 



The il8 returns the condition of the active workspace. It returns a 
value of to indicate that the workspace is intact or a nonzero 
number to indicate that the workspace has suffered some kind of damage, 
If I-beam 18 returns a nonzero value, APL attempts to correct the 
damage . 

il9 Returning the Keying Time 



132:1.181 



The il9 calculates the amount of time that the keyboard has been 
unlocked awaiting input during the current APL session. Time is 
expressed in 60ths of a second. i-beam 19 is useful for instructional 
programs that time the response of students' answers. It returns one 
component of the information available from the DAI system variable 
(Section 4.2.1) . 

i20 Returning the Time of Day 

x20 
3446581 



The i2 returns the current time of day. It returns the time from 
midnight in 60ths of a second. To request this number in hours, min- 
utes, and seconds, specify the following: 

3t24 60 60 60t:i:20 
15 57 40 

i20 returns one component of the information available from the UTS 
system variable (Section 4.2.22). 

i21 Returning the CPU Time 



:21 



3496 



The i21 returns the CPU time used since you signed on in the current 
APL session. Time is expressed in 60ths of a second. i-beam 21 is 
useful in comparing the execution times of different programs. You 
can include i21 in a function and make the execution of that function 
dependent on the compute time used so far in the session. i21 returns 
one component of the information available from the DAI system vari- 
able (Section 4.2.1). 
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i22 Returning Workspace Availability 



18219 



The i22 returns the maximum amount to which the active workspace can 
increase. The size is given in words and is obtained by subtracting 
the current data segment size from the maximum data segment size. 
I-beam 22 can be used in a function whose execution is dependent on 
the space available in the workspace. It is similar to the UWA system 
variable (Section 4.2.25); however, i22 returns the number of words 
available, instead of the number of bytes (where 4 bytes = 1 word) . 

i2 3 Returning the System Job Number 

:i; 2 3 

17 



The i23 returns the system job number associated with the current APL 
session. The job number is returned in base 10 notation. To request 
this number in octal, specify: 

10x<3r8)T:i:23 



I-beam 23 is equal to the UUL system variable (Section 4.2.20). 
i24 Returning the APL Sign-on Time 

20S8600 



The i24 returns the time when you began the current APL session. It 
returns the time from midnight in 60ths of a second. i-beam 2 4 re- 
turns one component of the information available from the UAI system 
variable (Section 4.2.1). 

i25 Returning the Current Date 

:i:25 

70579 



The i25 returns the current date. The date is displayed in the form 
MMDDYY in base 10 notation. To format a 3-element vector represent- 
ing the date, specify the following: 

(3rl00)T:i;25 
7 5 79 

I-beam 2 5 returns one component of the information available from the 
UTS system variable (Section 4.2.22). 
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i26 Returning a Line Number 



The i2 6 returns the line number of the statement currently being 
executed or about to be executed. The scalar returned by i-beam 2 6 
is the first element of the vector returned by i27 and is the first 
line number in the state indicator. This number represents the line 
at which the innermost function in the state indicator was suspended 
or is currently executing. 

i26 is a particularly helpful function when used in branch statements. 
You resume execution by specifying ->i26 rather than entering the line 
number displayed at the time the last function was suspended. i2 6 
returns one component of the information available from the ULC system 
variable (Section 4.2.12). 

i27 Returning a Vector of Line Numbers 



The i27 returns a vector of function line numbers currently in the 
state indicator. The first element of the vector is the line number 
returned by i26 and represents the line at which the innermost func- 
tion was suspended or is currently executing. If an empty vector is 
returned, this indicates that no functions are suspended or executing, 

i27 can be used as an aid in resuming function execution without in- 
cluding a specific line number at which the function was suspended. 
For example, you can define function RES as follows: 

V r:^ ■<■■ ]■■■•: l-i: S 

i::2:] '^' 

nKESUME i:;:xi:::cut:i;qn w:i:th 



i2 7 returns the same information available from the DLC system vari- 
able (Section 4.2.12). 

i2 8 Returning the Terminal Character Set 

;i:28 



The i28 returns the character set of the output device associated with 
the workspace. This device is the user's terminal unless otherwise 
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specified by the ) OUTPUT system command (Section 7.9). The integer 
scalar returned by i-beam 28 is one of the following: 

Value Meaning 

APL character set 

1 TTY character set 

i28 is related to the UTT system variable (Section 4.2.22). 

i29 Returning the User's Project-Programmer Number 

;i:29 
4 132 



The i29 returns the project-programmer number associated with the 
current session. The number is returned as a 2-element vector in base 
10 notation. To format this number in octal, specify the following: 

:l.0x (6f 8)t;i:29 

4 204 



i29 returns one component of the information now available from the 
UAI system variable (Section 4.2.1). 

i30 Clearing the State Indicator 

:i:30 
) s :i: 



The i3 clears the state indicator. It has the same effect as typing 
a series of right arrows (-^) , one for each suspended function. See 
Section 5.4.9 for a description of state indicator clearing techniques, 
i30 removes from the system all pendent and suspended functions calls. 
As the above example indicates, an )SI command issued after the clear 
request results in the display of a blank line. 

i31 Returning the Number of APL Statements 

;x;3:l. 
Si9 



The i31 returns the number of APL statements that have been executed 
since the current session began. This function is useful in evaluating 
the performance of programs in the workspace. 
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i32 Returning the Number of APL Operations 

x32 
837 



The i32 returns the number of APL operations that have been executed 
since the current session began. There may be several operations 
performed in each APL statement. For example; 



This statement contains two operations: addition and assignment. Like 
I-beam 31, this function is useful in evaluating program performance. 

i3 3 Returning the Time Used 
x33 



On TOPS-10, the i33 returns the number of kilo-core-seconds since 
sign-on. If the GETTAB UUO is privileged in the system, i33 returns 
a value of zero. On TOPS-20, i33 also returns 0. 
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APPENDIX D 
SPECIFYING TOPS-20 DIRECTORIES 



TOPS-2 provides two ways for you to access another user's directory. 
The first way is with a logical name in place of the device name; the 
second way is with a project-programmer number instead of a directory 
name. You can use either method with APL; however, the use of logical 
names is recommended. 



NOTE 

When you see a project-programmer number 
(for example, [4,204] in this manual or 
in an error message, use the TRANSL com- 
mand to find out its corresponding di- 
rectory name. Refer to Section D.2.1. 

For more information about referencing other users' files, refer to 
the TOPS-20 User's Guide. 



D.l USING LOGICAL NAMES 

To use a logical name in accessing another user's directory: 

1. Give the DEFINE SYSTEM command to define a logical name (of 
no more than six characters) as the other user's directory 
name. 

2 . Use the logical name in place of the device name when typing 
the file specification. 



D.1.1 Giving the DEFINE Command 
To give the DEFINE command: 

1. Type DEFINE and press the ESC key; the system prints 

(logical name) . 
(3Def:i:ne (logical name) 

2. Type the logical name (an ending colon is optional) and press 
the ESC key. The system prints (AS) . 

(» DEFINE (log:i:cAI... NAME) ^i^K J (^S) 
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3. Type the structure and the directory name (enclosed in angle 
brackets) and press the RETURN key. The system prints an (9. 

©DEFINE (LOGICAL NAME) BAKt < AS ) DATA : <SCHULERT> 

To check the logical name, specify the INFORMATION (ABOUT) LOGICAL- 
NAMES system command. 

eiNFOF^MATIGN (ABOUT) LOGICAL -NAMES (OF) 
B A K : ^ :::■ D A T A t < S C l-l U I... E R T !> 



D.1.2 Using the Logical Name 

Once you define a logical name, you can then include it in an APL 
expression in place of a device name. 

The following example shows how to load a workspace from the directory 
named DATA: <SCHULERT> . (Remember, you have already defined the logical 
name BAK: as DATA: <SCHULERT> . ) 

) LOAX:' »AI< ♦ TEST 

sfWBD ;|. 5 J 45? 03 24-o(:-T -78 S'^^' 



D.2 USING PROJECT-PROGRAMMER NUMBERS 

To use a project-programmer number in accessing another user's 
directory: 

1. Give the TRANSL command to find the corresponding project- 
programmer number for the desired directory name. 

2. Include the project-programmer number after the file type. 

You do not have to define a logical name when using a project- 
programmer number. However, project-programmer numbers may not remain 
constant over time; therefore, use logical names whenever possible. 



D.2.1 Using the TRANSL Command 

To run the TRANSL command: 

1. Type TRANSL and press the ESC key. The system prints 
TRANSLATE (DIRECTORY) . 

ir-TRANSLATE (DIRECTORY) 
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2. Type the structure, the directory name, and press the RETURN 
key. The default structure is your currently connected 
structure. The system prints the corresponding project- 
programmer number. 

G? ■}■ R A N S I... A T E ( B I R E C T R Y ) R S t < S C l-l U L E R T > 

p s t < 3 c l-l ij I... i;;; r t > < :t: s ) i"* b : i:: 4 y ? 5 ::i 
0? 



You can also use TRANSL to verify that a project-programmer number is 
correct. To do this, replace the directory name with the project- 
programmer number. 

(» T RAN S L A T E < li' I R E C J R Y ) [: 4f s- 7 5 ::i 

B A 8 1 c J i:: 4 y 7 5 ::i ( :i; s > b a s :i: c : <: r' s r i :> 

Q 



D.2.2 Using the Project-Programmer Number 

To use a project-programmer number in APL, include it in an expression 
after the file type. 

The following example shows how to load an APL workspace from the 
directory named SCHULERT, using a project-programmer number. (Remem- 
ber, you have already translated the directory name.) 

)i...aAD TEST i:; 4 y 7;;;; "I 
s A V I:;; D il. 3 ? 5 2 t 2 3 27 ■ '"■ ^' ^' ■■■■ 79 5 '"' 
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The following is a sample APL terminal session. The sign-on and sign- 
off may be different at each installation, but the APL statements will 
be the same . 

teririinaJ. ♦ ^l.^ 

<^ ^' ••- ••• 2 ^■' ^" <•• ••> '"' ■•> "i" 1-^ M • ••■ 20 '^ '"■ I™ ••■> '"■ 2(407) 

y y y 22^ 9 1 4 3 ♦ 3 9 w ^" ^•' '•' '•" ">■ ^^ f^ ■'■ 2 7 ' '-^ '< ••• 7 9 ^ n s e u i... f^ \" 4 j, 2 4 ."I 

CUEAR ws 

flSET PAGE Wli:iTH TO 72 

r.FW<-72 
i;;|PW 



72 



14 



f) :i: M M E D X A f E E V A I... U A 7' X O M 

2*-3 

p, R E s ij I... r w A s w o r- :r f< t> ii;: ?s' r' i;i: t> 

ft EVALUATE ON PHirOM RIGHT TO I...EFT 
2^3 + 4 



ft Ii-: i„ k; m e ?•< r- ■•• b t- ■••• e i... n-: m i;;; hj r a d d :i: r- ;i: o h 

4 3t-2 4 
6 7 

ft SCALAR AFPL.. :i:ED to a V EC to Mi: 

SX4 9 2 
20 45 :l.0 

ftr:i;LV3:s:LON xs fi...oat;i:ng poxnt 

Sv-3 ■■"2 5 
1*666666667 ""2.5 1 

ft NOTE d:i:fI"K::rence between •■■■ ANX:< 

8 -3 2 9 
S 6 "1 

ftMONAj:>:i:c B:r. vxbe :r. s reciprocal 

■■■'"i B '■' 
0*2 0»:l^5' 0*^5 

ft E ;■( i==- o ii E )i r X A r- :n o ii 



A 9 ':> A •■■■• '.' 
2 3 :U4:l.42!i:35<ii2 

ft :i: N t' E J< (s lii: ? i e i-: (^ r o i-;: 
12 3 4 5 

ft C E X L. X N G (=■■ 1.1 ii C r X O ii 

i3.2 ■■■■4»2 7,6 -"IS. 
4 ""4 8 ■■18 



E-1 



TERMINAL SESSION 



flPUOOK FUNCTION 

L3.2 ~4,2 7.6 ""IB. 6 
3 ""5 7 "19 

flFi:EI._ATXDNAL. LESS THAN FUNCTION 
e ;IV 27<18 

:l 

ft COMPRESS FUNCTirON 

(8 19 27<1B)/B 19 27 



8 



ft ASS TONS VECTOR TO N 

h<-2m7 

ft S E I... E Q T S E I... E: M E M T S 

10 10 10 i/>-^ 
7 9 

fll SELECTS 
1/2 

flO REJECTS 
0/2 

ftNULL VECTOR PRINTS AS JBLANK LINE 
ftNUMBER OF ELEMENTS IN NULL VECTOR IS () 
fO/2 







ftRESinUE N Mor> 3 

31 N 
12 12 

ft NUMBERS NOT DIVISIBLE BY 3 

110 110 

ft NUMBERS OF N =: TO 3 OP: NOT DIVISIBLE BY 3 
((3 = W)vO?i3|H)/N 

3 4 5 7 8 

ftLEAST INDEX OF FUNCTION 

5 7 9 11 \ 9 6 11 
3 5 4 

ft FIFTH AND SEVENTH ELEMENTS OF N 

NC5 7:j 

7 9 

ft CATENATE FUNCTION 

HC3 4 7:1 y 20 12 13 
5 6 9 20 12 13 

ft DEFINE FUNCTION WITH A RESULT 

ft WITH I DUMMY ARCvUMENT AND 2 LOCAL VARIABLE 

ft LOOP AND END ARE LABELS 

ft FUNCTION IS TO FIND ALL PRIMES UP TO 

ft f> N V I N C^ L U D I M O f< 

VRfPRIMES N J DONE J D 

1:1 J i:'f-3 

C2J DONEf.N*->.2 

1:33 P:<-l+2x\l. "••l•^^^v•2 

1: 43 LOOP ♦ -> ( DONE < D ) /END 

USD P-i- ( ( i:'=.R ) vO?^i:' I •=;: ) /R 

1:6: DfRClfRlD] 

1:7:1 -^LOOP 

C83 ENDJRM 2yl=-: 

1:93 V 

ft FUNCTION IS CALLED WITH ;| 5 
PRIMES "IS 

1 2 3 5 7 11 13 
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flTPrrlNG ANOTHER P A IH; A M E T ti: P: 
PRIMES 3t 

1 2 3 5 7 11 13 17 19 23 29 

n ANSWER XS WRONG SINCE 31 IS PRIME 
flSET TRACE ON ALL. L. INES OF FUNCTION 
TAFP:IMESfta 
PRIMES 31 
PRIMES|:i;3 3 

PRiMES[;23 S» 567764363 



PRiMES|;3;3 


3 


5 


7 


9 11 13 15 17 19 21 23 25 '.. 


) 7 ':> <: 


PRIMES[:43 












PRIMES 1:53 


3 


5 


7 


11 13 17 19 23 25 29 




PRiMESf;^;] 


5 










PRIMES[;73 


4 










PRIMES|:43 












PRIMES|;:53 


3 


5 


7 


11 13 17 19 23 29 




PRIMES 1:6 3 


7 










PRiMEsny;] 


4 










PRIMESC43 


8 










PRIMESCiS] 


1 


2 


3 


5 7 11 13 17 19 23 29 




12 3 5 7 


11 




13 


17 19 23 29 




n TRACE 


CAUSED THE PRINCIPAL. VAL.UKi: OF 


THE 


flTR 


ACEEi 


LINE TO BE PRINTEti EACH TIME 


THE 


flUINE 


WAS 


E.XECUTETi 





flNOW <->ET STOP AT LINE 4 

SAFt=;:IMESf-4 

PRIMES 31 

pRiMESi;:i::i 3 

primes|::2:J 5»567764363 

PRIMES|:3;;| 3 5 7 9 11 13 15 17 19 21 23 25 27 29 

pRiMESi:4::i 

n DISPLAY VALUE OF Hi: 
R 

3 5 7 9 11 13 15 17 19 21 23 25 27 29 

flR SHOULD INCLUDE THE FOLLOWING 
Rf.R,31 

n CLEAR TRACE AND STOP VECTORS 
B&F-RXMESi-O 
TAFRIMESf-O 

fl CHECK STATE INDICATOR 
)SI 
PR I MESH' 4 "I ft 

fl RESTART KLXECUTION AT LINE .4 
■>A 

1 2 3 5 7 11 13 17 19 23 29 31 

flOPEN FUNCTION ANXj EX.! IT LINE 3 
VPRIMES 

i-9::i i:3::iF':<-i *-2x i l""i *-^'v-2v 
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V PRIMES 
riJ '"'^:fi1-i>X\|..":L*Hv-2 

/ 1 

\:31 H::f.l.f2x\|-'-llHv-2 

C4:] ^ 

flCAL..l,. FtJNCT J. ON 
l-l=i:3:MK:S 31 

1 2 3 5 7 11. 12 17 19 23 29 31 
flWRXTE- THE- t:i:me h-uhctxdn 

VTIME 



CI] 

i: 1 :] 

1:2 3 

1:3 J 



Vi'fTXMH J T 

2:«-60 60 60t(i< :i.21 ) 
T3;me;:p:<- T 

V 

fl :i: H 1 T I A I... ;i: z e t o c u r h;: 11;: fi r c r--- u r x m k;: 

TIMERf- ;i;21 

T X M E 

4 3 

flF-CND PRXMES .< 10000 

R. J. PRIMES 10000 

TXME 

7 32 

ft ?i UMBER OF pr:i:mes i 10000 

PR 
1230 

fli.. :i:sT THE (...AST 5 pr:i:mes <. 10000 
9931 9941 9949 9967 9973 

ft I.. IS T DEi":rNEi:> var:i:abi...I:;;s :i:n th;i:s workspace 

) VARS 
i( R TIMER 

ft ERASE R 
)ERASfii: R 

I-: 
il VAI...UE ERROR 
R 



ft VALUE EFJ-ROR BECAUSE R HO LONGER EXISTS 
ftL. IST VARIABLES AGAIE 

ft I... I s T V A R I A B I... i;;: s (^ g n x h 

) VARS 

TIMER 

ftp WAS OMIT tk;:!:- 

ft SAVE THIS WORKSAPCE UNX:'ER THE NAME MYWS . APL 
ft THEN LOG OFF 



10:27B8''^7^^^W^-79 2 PG< 



) OH" I"' 

I' 1' I' 2 2 > lot 2 7:54 2 7 ' ^ >i •■• 7 9 

C O N W E C T I::.- D QtAAl 1 5 <•■ l==' »-^ '1' -f- M •==■ t 00 t S 
315 STATEMENTS <^S6 OPERATIONS 

KlLLEiili JOB 19i' USEF\' M A SELL A y ACCOUNT APL y TTY 22 y 
AT 27-JUN-79 10 J 27 J 54 y USED 0t0:9 T.N 0:44:49 
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1-dimensional array, 2-4 
.AAS file extension, 7-6 
.ABI file extension, 7-6 
Absolute fuzz, 2-15 
Access, 

multiple-user, 7-16 

random, 7-3 

sequential, 7-2 

shared file, 7-36 

single-user, 7-16 

synchronizing, 7-36 
Access file, 

random, 7-14 
Access methods, 

file, 7-2 
Account information, 

storing, 4-2 
Action commands, 5-2 
Active workspace, 1-1, 5-3 
Active workspace, 

clearing the, 5-8 

identifying the, 5-15 

saving, 5-13 
.ADA file extension, 7-6 
Add (+) , 1-6 

Adding function lines, 6-8 
UAI system variable, 4-2 
.AIS file extension, 7-6 
UALPHA system variable, 4-3 
Alphabetic characters, 4-3 
Alphabet ics, 

underlined, 4-3 
UALPHAU system variable, 4-3 
AND (a) function, 3-6 
APL, 

interacting with, 1-8 

returning to, 5-32 

starting, 1-8 
APL character set, 1-5, 1-6 
APL libraries, 5-7 
APL termination commands, 5-32 
APL-keyboard terminals, 1-3 
UAPPEND system function, 7-17, 

7-21 
Arguments, 

dummy, 6-2 
Array, 

1-dimensional, 2-4 

building an, 3-45 

constructing an, 3-37 

reshaping an, 3-37 

rotating an, 3-41 
Array indexing, 2-11 
Array output, 2-9 
Arrays, 2-5 

subscripting, 2-11 



/AS switch, 7-6, 7-10 
/AS* switch, 7-6, 7-10 
ASCII character set, 4-3, 4-4 
ASCII sequential file, 7-3 
ASCII sequential I/O, 7-10 
ASCII system variable, 4-3, 

4-4 
UASS system function, 7-4 
Assigning a file, 7-4 
Assignment (-«-) function, 2-7 
Assignment statement, 2-7 
Atomic vector, 4-9 
UAUS system variable, 4-7 
Auto- save, 4-7 
Automatic save, 4-7 
Automatically, 

saving a workspace, 4-7 
UAV system variable, 4-8, 4-9 
Availability, 

workspace, C-3 
Available work area, 4-28 



Bare output, 2-16 
Bare-output mode, 2-22 
Binary-access file, 7-18 
Binary-access files, 

sharing, 7-19 
Binary-access I/O, 7-20 
Binary-access sequential file, 

7-3 
Blocking factor, 7-15 
)BLOT system command, 5-36 
Body, 

function, 6-1, 6-2 
Box (D) , 2-17 
Branch (->■) function, 2-7 
Branch statement, 2-7, 6-14 
Branch statement, 

conditional, 6-15 

unconditional, 6-15 
Branching, 6-14 
UBREAK system function, 4-29, 

6-23 
/BS switch, 7-6, 7-19, 7-28 
/BS* switch, 7-6, 7-19 
/BU switch, 7-19 
Building an array, 3-4 5 



)C system command, 5-32 
)CALL system command, 5-32 
Canonical representation, 4-30 
Catenate (,) function, 3-12 
Ceiling (f) function, 3-3 
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Changing the file 

specification, 7-8 
Channel, 7-4, 7-20, 7-21 
Character, 

escape, 1-5 
Character constant, 2-3 
Character conversion, 4-32 
Character data, 2-3 
Character input, 2-16 
Character set, 

APL, 1-5, 1-6 

ASCII, 4-3, 4-4 

terminal, C-4 
Character vector, 2-4 
Character-editing procedures, 

6-11, 6-13 
Character-input mode, 2-17 
Characteristics , 

workspace, 5-3 
Characters, 

alphabetic, 4-3 

control, 4-15 

converting numerics to, 
3-64, 3-68 

editing, 1-11 

overstrike, 1-7 

single strike, 1-6 
) CHARGE system command, 5-36 
UCHS system function, 7-31 
UCIQ system function, 7-25 
Circle (o) functions, 

dyadic, 3-4, B-3 
Classification, 

name, 4-34 

symbol, 6-3 
) CLEAR system command, 5-8 
Clear workspace, 1-1 
Clearing the active 

workspace, 5-8 
Clearing the state indicator, 

6-19, C-5 
Closing a file, 7-7 
UCLS system function, 7-7 
Colon ( : ) , 1-6 
Comma ( ,) , 3-33, 3-36 
Command , 

)BLOT system, 5-36 

)C system, 5-32 

)CALL system, 5-32 

) CHARGE system, 5-36 

) CLEAR system, 5-8 

CONTINUE, 1-10 

) CONTINUE system, 1-9, 5-5, 
5-33 

)COPY system, 5-21 

) CREATE system, 7-15 

DEFINE, D-1 

)DIGITS system, 5-27 

)DROP system, 5-9 



Command (Cont.) 

)ECHO system, 5-28 

)ERASE system, 5-22 

)FNS system, 5-23 

) GROUP system, 5-2 3 

)GRP system, 5-24 

)GRPS system, 5-24 

)INPUT system, 7-40 

)LIB system, 5-10 

)LOAD, 5-12 

)MAXCORE system, 5-16 

)MINCORE system, 5-17 

)MODE system, 5-29 

)MON system, 1-9, 5-34 

)OFF system, 1-9, 5-34 

) ORIGIN system, 5-30 

)OUTPUT system, 7-40 

) OWNER system, 5-18 

)PASSWORD system, 5-13 

)PCOPY system, 5-25 

)R system, 5-35 

REENTER, 1-10 

)RUN system, 5-35 

)SAVE system, 5-13 

)SEAL system, 5-18 

SET TTY WIDTH, 5-32 

)SI system, 5-6, 5-25, 6-18, 
6-19 

)SIV system, 5-6, 5-26, 
6-19 

)SIZE system, 5-19 

)TABS system, 5-30 

TERMINAL WIDTH, 5-32 

)TIME system, 5-19 

TRANSL, D-2 

)VARS system, 5-27 

)VERSION system, 5-20 

) WIDTH system, 5-31 

)WSID system, 5-15 
Command format , 

system, 5-2 
Command level , 

operating system, 5-34 
Command lines, 6-6 
Commands, 

action, 5-2 

APL termination, 5-32 

inquiry, 5-2 

miscellaneous, 5-36 

system, 5-1, B-16 

workspace-content, 5-2 

workspace-control, 5-7 

workspace-environment, 5-27 
Comments, 2-5 
Communication , 

system, 4-1 
Comparison tolerance, 2-15, 

4-14 
Component, 7-16 
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Components, 

expression, 2-2 
Compression (/) function, 

3-15 
Computer time, 4-2 
Conditional branch statement, 

6-15 
Connect time, 5-19 
Considerations , 

error handling, 6-23 
Constant, 

character, 2-3 
numeric, 2-3 
Constants, 2-3 
Constructing an array, 3-37 
CONTIN workspace, 5-5 
CONTINUE command, 1-10 
) CONTINUE system command, 

1-9, 5-5, 5-33 
CONTINUE workspace, 5-5 
Control characters, 4-15 
Conversion, 

character, 4-32 
Converting numerics to 

characters, 3-64, 3-68 
Copy, 

protected, 4-36, 5-25 
Copy lock, 5-18 
)COPY system command, 5-21 
Copying a workspace, 4-36 
Copying objects, 5-21 
UCOQ system function, 7-25 
Correcting a line, 1-10 
CPU time, 4-2, 5-19, C-2 
UCR system function, 4-30, 

4-33 
) CREATE system command, 

7-15 
nCT system variable, 2-15, 

4-14 
CTRL system variable, 4-15 
CTRL/C, 1-11 
CTRL/R, 1-11 
CTRL/U, 1-11 
Current date, 4-27, C-3 
Current time, 4-27 



/DA switch, 7-6, 7-16 
UDAS system function, 7-6 
Data, 

character, 2-3 

numeric, 2-3 
Data files, 1-2 
Data types, 7-20 
Date, 

current, 4-27, C-3 
Deal (?) function, 3-17 



Deassigning a file, 7-6 
Decode (i) function, 3-18 
DEFINE command, D-1 
Defined functions, 6-6 
Defining a function, 6-1 
Defining a group, 5-2 3 
Definition, 

function, 6-1 
Delay, 4-31 

Delaying execution, 4-31 
Delete, 5-22 
DELETE, 1-11 
Delete a record, 7-17 
Deleting function lines, 6-9 
Deleting stored files, 5-9 
Deleting stored workspaces, 

5-9 
Delta (A) , 1-6 
UDEQ system function, 7-36 
Description, 

inner product, 3-71 

outer product, 3-74 
Designators, 

terminal, 1-2, 1-3 
Despersing a group, 5-23 
Dev:, 2-6 
Device characteristics, 

returning, 7-33 
/DI switch, 7-6, 7-16 
Diamond (0) , 1-6 
Dieresis (") , 1-6 
Digits, 4-21 

significant, 5-27 
) DIGITS system command, 5-27 
Dimensions, 

transposing, 3-46 
Direct-access file, 7-3, 7-14 
Direct-access files, 

sharing, 7-16 
Direct-access I/O, 7-16 
Directories, 

specifying TOPS-20, D-1 
Directory, 5-10 
Directory name, D-2 
[directory], 2-6 
Displaying a group list, 

5-24 
Displaying a variable list, 

5-27 
Displaying function lines, 

6-10 
Displaying function names, 

5-23 
Displaying group members, 

5-24 
Displaying session 

information, 5-36 
Displaying the state 
indicator, 5-26 
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Divide, 

quad, 3-50, 3-52 
Divide (§) function, 

matrix, 3-52 
Divide (v) function, 3-3 
UDL system function, 4-31 
Dollar format ($) function, 

3-59 
Domino, 3-50, 3-52 
Down arrow (4-) , 3-19 
Drop i-^) function, 3-19 
)DROP system command, 5-9 
Dummy arguments, 6-2 
/DUMP switch, 7-4, 7-28 
UDVC system function, 7-33 
Dyadic, 3-1 
Dyadic circle (o) functions, 

3-4, B-3 
Dyadic format (t) function, 

3-65 
Dyadic function, 6-7 
Dyadic functions, 6-2 
Dyadic transpose (^) 

function, 3-48 
Dynamic localization, 6-4 



)ECEO system command, 5-28 
Echoing, 

error line, 5-28 
Editing, 

function, 6-11, 6-13 

immediate mode, 1-11 

immediate-mode, 6-14 

keyboard, 1-10 
Editing characters, 1-11 
Editing the function, 6-7 
Editing the function header, 

6-11 
Encode (t) function, 3-22 
Ending the session, 1-9, 

5-33 
UENQ system function, 7-36 
Epsilon, 3-35 

Equal to (=) function, 3-5 
Equivalents, 

mnemonic, 1-5 
) ERASE system command, 5-22 
Erasing a named object, 

4-31 
Erasing global names, 5-22 
Error handling, 2-10 
Error handling 

considerations, 6-2 3 
Error line echoing, 5-28 
Error messages, A-1 

storing, 4-16 
Error numbers, A-1 



UERROR system variable, 4-16, 

6-23 
Error trapping, 6-23 
Error trapping examples, 

6-24 
Errors, 

signalling, 4-39 
trapping, 4-25 
Escape character, 1-5 
Escaping from input mode, 

2-19 
Evaluated input, 2-16 
Evaluated input prompt, 

4-23 
Evaluated-input mode, 2-17 
Evaluation, 2-8 
UEX system function, 4-31 
Examining the state 

indicator, 6-18 
Examples, 

error trapping, 6-24 
Execute (e) function, 3-54 
Execute function, 5-37 
Execute (i) function, 

extended, 3-57 
Executing a function, 6-1 
Executing functions, 
reporting on, 4-20 
Executing the function, 

6-14 
Execution, 

delaying, 4-31 
interrupting, 6-17 
suspending, 4-29 
suspending function, 6-17 
Execution modes, 2-1 
Exit, 5-32, 5-34 
Expansion (\) function, 3-25 
Explicit result, 6-2, 6-3 
Exponentiate function, 3-3 
Expression, 

latent, 4-20 
Expression components, 2-2 
.ext, 2-6 
Extended execute {i) 

function, 3-57 
Extended functions, 3-50, 

B-6 
External interface, 5-32, 

5-35 



Factorial (I) function, 3-3 
DFCM system function, 7-3 5 
UFI system function, 4-32, 

4-40 
File, 

ASCII sequential, 7-3 
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File (Cont.) 

assigning a, 7-4 

binary-access, 7-18 

binary-access sequential, 
7-3 

closing a, 7-7 

deassigning a, 7-6 

direct-access, 7-3, 7-14 

internal sequential, 7-3, 
7-13 

random access, 7-14 

sequential, 7-9 

.TMP, 4-8 
File access, 

shared, 7-36 
File access methods, 7-2 
File extension, 

.AAS, 7-6 

.ABI, 7-6 

.ADA, 7-6 

.AIS, 7-6 
File I/O functions, B-15 
File information, 

returning, 7-35 
File input, 2-16, 7-4 
File input modes, 7-11 
File locks, 7-38 
/file org switch, 7-4 
File organization, 7-2 

returning, 7-31 
File organization switches, 

7-6 
File output, 2-16, 7-4 
File sharing information, 

7-34 
File specification, 

changing the, 7-8 
File specifications, 2-6 
File system, 7-1 
File system functions, B-12 
Filename, 2-6 
Files, 

data, 1-2 

deleting stored, 5-9 

sharing binary-access, 
7-19 

sharing direct-access, 
7-16 
Fix, 4-33 

Floor (L) function, 3-3 
UFLS system function, 7-34 
)FNS system command, 5-23 
Format, 

system command, 5-2 
Format {$) function, 

dollar, 3-59 
Format (¥) function, 

dyadic, 3-65 

monadic, 3-64 



Formatting tables, 3-6 5 
Function, 3-1 

AND (A) , 3-6 

UAPPEND system, 7-17, 7-21 

Assignment (-«-) , 2-7 

UASS system, 7-4 

Branch (->) , 2-7 

UBREAK system, 4-29, 6-23 

catenate (,), 3-12 

ceiling ( D , 3-3 

nCHS system, 7-31 

nciQ system, 7-25 

UCLS system, 7-7 

compression (/) , 3-15 

UCOQ system, 7-25 

nCR system, 4-30, 4-33 

UDAS system, 7-6 

deal (?) , 3-17 

decode (i) , 3-18 

defining a, 6-1 

UDEQ system, 7-36 

divide (■^) , 3-3 

UDL system, 4-31 

dollar format {$) , 3-59 

drop (+) , 3-19 

UDVC system, 7-33 

dyadic, 6-7 

dyadic circle (o) , B-3 

dyadic format (w) , 3-65 

dyadic transpose (^) , 3-48 

editing the, 6-7 

encode (t) , 3-22 

UENQ system, 7-36 

equal to (=) , 3-5 

UEX system, 4-31 

execute, 5-37 

execute (e) , 3-54 

executing a, 6-1 

executing the, 6-14 

expansion (\), 3-25 

exponentiate (*) , 3-3 

extended execute (i) , 
3-57 

factorial (I), 3-3 

UFCM system, 7-35 

UFI system, 4-32, 4-40 

floor (L), 3-3 

UFLS system, 7-34 

UFX system, 4-33 

grade down (t) , 3-27 

grade up (4) r 3-28 

greater than (>) , 3-5 

greater than or equal to 
(^) , 3-5 

index generator (?), 3-3 

index of (?) , 3-31 

input quad (0), 7-16, 
7-20, 7-4, 7-10, 7-13 

laminate, 3-33 
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less than (<) , 3-5 

less than or equal to (<) , 
3-5 

locking a, 6-22 

logarithm (®) , 3-3 

magnitude ( | ) , 3-3 

matrix divide (i) , 3-52 

matrix inverse (@) , 3-50 

membership {e) , 3-35 

minus (- ) , 3-3 

monadic, 6-6 

monadic format (t) , 3-64 

monadic transpose (is?) , 
3-46 

UMTP system, 7-28 

multiply, 3-3 

NAND (A) , 3-6 

UNC system, 4-34 

UNL system, 4-35 

NOR (V) , 3-6 

NOT (~) , 3-6 

not equal to ('') , 3-5 

OR (v) , 3-6 

output quad (0), 7-16, 
7-4, 7-10, 7-21 

pendent, 6-18 

pi (o) , 3-3 

plus (+) , 3-3 

UQCO system, 4-36, 5-21 

UQLB system, 4-36, 5-12 

UQPC system, 4-36, 5-25 

quad, 2-17 

quad-del (M) , 2-18 

question (?), 3-3 

quote (t) , 3-68 

quote-quad (E) , 2-17 

ravel ( , ) , 3-36 

URENAME system, 7-8 

reshape (p) , 3-37 

residue ( I ) , 3-7 

reverse (<|) and e) , 3-39 

roll (?), 3-9 

rotate (<t)) , 3-41 

shape (p ) , 3-43 

USIGNAL system, 4-39, 6-23 

suspended, 5-26, 6-18 

take (f ) , 3-45 

unquote (i) , 3-54 

user-defined, 6-1 

UVI system, 4-40 

writing a, 6-1 
Function body, 6-1, 6-2 
Function definition, 6-1 
Function editing, 6-11, 6-13 
Function execution, 

suspending, 6-17 
Function header, 6-1, 6-2 



Function header, 

editing the, 6-11 
Function input, 6-5 
Function lines, 

adding, 6-8 

deleting, 6-9 

displaying, 6-10 

inserting, 6-8, 6-9 

replacing, 6-8 
Function list, 5-23 
Function name, 6-3 
Function names, 

displaying, 5-23 
Function output, 6-5 
Function representation, 

4-30 
Function-execution mode, 

2-1 
Functions, 

defined, 6-6 

dyadic, 6-2 

dyadic circle, 3-4 

extended, 3-50, B-6 

file I/O, B-15 

file system, B-12 

keyboard I/O, B-15 

logical, 3-6, B-3 

monadic, 6-2 

niladic, 6-2 

pendent, 5-26 

primitive mixed, 3-10, 
B-4 

primitive scalar, 3-2, 
3-3, B-2 

relational, 3-5, B-3 

reporting on executing, 
4-20 

system, 4-1, 4-28, B-11 
Fuzz , 

absolute, 2-15 

relative, 2-15, 4-14 
UFX system function, 4-33 



GAG, 

TTY NO, 4-18 
UGAG system variable, 4-18 
Generating a mask, 5-36 
Generator, 

random number, 4-23 
Global names, 

erasing, 5-22 
Global symbols, 6-4 
Go to (^) , 2-7 

Grade down function (t) , 2-7 
Grade up function (4^) ^ 3-28 
Greater than (>) function, 3-5 
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Greater than or equal to (>) 

function, 3-5 
Group , 

defining a, 5-23 

despersing a, 5-23 
Group list, 

displaying a, 5-23 
Group members, 

displaying, 5-24 
Group name, 6-3 
) GROUP system command, 5-23 
Groups, 5-6 

)GRP system command, 5-24 
)GRPS system command, 5-24 



Handling, 




error, 2-10 


Header, 


7- 


-20, 7-21, 7-25 


Header, 






editing 


the function, 6-11 


function, 6-1, 6-2 


Help, 1-8 




High minus ( ) , 2-3 


Histogram 


(I), 1-7 


I-beam 


17, 


C-1 


I-beam 


18 


C-2 


I-beam 


19 


C-2 


I-beam 


20 


C-2 


I-beam 


21 


C-2 


I-beam 


22 


C-3 


I-beam 


23 


C-3 


I-beam 


24 


, C-3 


I-beam 


25 


, C-3 


I-beam 


26 


C-4 


I-beam 


27 


C-4 


I-beam 


28 


C-4 


I-beam 


29 


C-5 


I-beam 


30 


C-5 


I-beam 


31 


C-5 


I-beam 


32, 


C-6 


I-beam 


33. 


C-6 



I-beams, C-1 

I.D., 

workspace, 5-15 

I/O, 

ASCII sequential, 7-10 
binary-access, 7-20 
direct-access, 7-16 
internal sequential, 7-13 
terminal, 2-16 

I/O functions, 
file, B-15 
keyboard, B-15 



Identifiers, 

illegal, 2-2 

legal, 2-2 
Identifying the active 

workspace, 5-15 
Identity elements, 3-75 
Illegal identifiers, 2-2 
Immediate mode, 2-1 
Immediate mode editing, 

1-11 
Immediate -mode editing, 

6-14 
Inactive workspace, 1-1 
Index generator (?) function, 

3-30 
Index of (?) function, 

3-31 
Index origin, 2-15, 4-19, 

5-30 
Indexing, 

array, 2-11 
Indicator, 

state, 5-6 

time limit, 4-24 
Information, 

displaying session, 5-36 

file sharing, 7-34 

returning file, 7-35 

storing account, 4-2 

symbol table, C-1 
Inner product description, 

3-71 
Inner product operator, 

3-70 
Input, 

character, 2-16 

evaluated, 2-16 

file, 2-16, 7-4 

function, 6-5 

quad, 2-16 

quad-del, 2-16 

quote-quad, 2-16 

unedited, 2-16 

validating, 4-40 
Input mode, 

escaping from, 2-19 
Input modes, 

file, 7-11 
Input prompt, 

evaluated, 4-23 
Input quad (S) function, 
7-16, 7-20, 7-4, 7-10 
7-13 
) INPUT system command, 7-4 
Inquiry commands, 5-2 
Inserting function lines, 

6-8, 6-9 
Interacting with APL, 1-8 
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Interface, 

external, 5-32, 5-35 
Internal sequential file, 

7-3, 7-13 
Internal sequential I/O, 

7-13 
Interrupting execution, 

1-10, 6-17 
Interruptions , 

preventing, 4-18 
Inverse (i) function, 

matrix, 3-50 
Inversion, 3-50 
Inverting a matrix, 3-50 
UIO system variable, 4-19 
Iota, 3-30, 3-31 
/IS switch, 7-6, 7-13 
/IS* switch, 7-6, 7-13 



Job number, 4-2 8, C-3 
Jot (°) , 1-7 



Keyboard editing, 1-10 
Keyboard I/O functions, 

B-15 
Keying time, C-2 
Keyword mnemonics, 1-2 



Line width, 

output, 4-22 
LINEFEED, 1-11 
Lines, 

multi-statement, 2-7 
List, 

displaying a group, 5-24 

displaying a variable, 
5-27 

function, 5-23 

name, 4-35 
Listing workspace names, 

5-10 
Literal vector, 2-4 
)LOAD command, 5-12 
Loading a workspace, 4-36 
Local symbols, 6-4 
Localization, 

dynamic, 6-4 
Lock, 

copy, 5-18 
Lock numbers, 7-38 
Locking a function, 6-22 
Locks, 7-37 

file, 7-38 
Logarithm (®) function, 3-3 
Logical expression, 6-15 
Logical functions, 3-6, B-3 
Logical names, D-1 
Logout, 5-34 
ULX system variable, 4-21 



Labels, 

statement, 6-16 
Laminate (,) function, 3-33 
Lamp (o) , 3-59, 6-6 
Language syntax, 2-1 
Latent expression, 4-21 
ULC system variable, 4-20, 

6-18 
Legal identifiers, 2-2 
Length, 7-20, 7-21 
Length, 

line, 5-31 
Less than (<) function, 3-5 
Less than or equal to (<) , 

3-5 
)LIB switches, 5-11 
)LIB system command, 5-10 
Libraries, 

APL, 5-7 
Limit, 

time, 4-24 
Line, 

correcting a, 1-10 
Line length, 5-31 
Line number, C-4 



Magnetic tape, 7-27 
Magnitude (|) function, 3-3 
Mask, 

generating a, 5-36 
Matrix, 2-5 

inverting a, 3-50 
Matrix divide (i) function, 

3-52 
Matrix inverse (i) 

function, 3-50 
)MAXCORE system command, 

5-16 
Maximum workspace size, 

5-16 
Members, 

displaying group, 5-24 
Membership (e) function, 

3-35 
Messages, 

error, A-1 
)MINCORE system command, 

5-17 
Minimum_workspace size, 5-17 
Minus ( ) , 
high, 2-3 



Index-8 



INDEX (CONT.) 



Minus (-) function, 3-3 

Miscellaneous commands, 5-36 

Mixed, 3-1 

Mixed functions, 

primitive, 3-10, B-4 

Mixed output, 2-16 

Mixed-output mode, 2-21 

Mnemonic equivalents, 1-5 

Mnemonics, 
keyword, 1-2 

Mod, 3-7, 3-22 

Mode, 

bare-output, 2-22 
character-input, 2-17 
escaping from input, 2-19 
evaluated- input, 2-17 
function-execution, 2-1 
immediate, 2-1 
mixed-output, 2-21 
normal, 2-19 
output, 5-29 
quad-del, 2-18, 2-22 
quad- input, 2-17 
quad-output, 2-19 
quote-quad, 2-17, 2-22 
terminal, 5-2 9 
unedited-input, 2-18 

)MODE system command, 5-29 

Modes, 

file input, 7-11 

Modulo representation, 3-7, 
3-22 

)MON system command, 1-9, 
5-34 

Monadic, 3-1 

Monadic format (v) function, 
3-64 

Monadic functions, 6-2, 6-6 

Monadic transpose (^) 
function, 3-46 

Monitor level, 1-9, 5-33, 
5-34 

UMTP system function, 7-28 

Multi- statement lines, 2-7 

Multiple-user access, 7-16 

Multiply (x) function, 3-3 



Name, 5-15 

directory, D-2 

function, 6-3 

group, 6-3 

variable, 6-3 
Name classification, 4-34 
Name list, 4-35 
Named object, 

erasing a, 4-31 



Names, 

displaying function, 5-23 

erasing global, 5-22 

listing workspace, 5-10 

logical, D-1 

workspace, 5-4 
NAND (?v) function, 3-6 
UNC system function, 4-34 
Negative number, 2-3 
Negative sign (-) , 2-3 
Niladic functions, 6-2 
UNL system function, 4-35 
No explicit result, 6-2, 

6-3 
NOR (V) function, 3-6 
Normal mode, 2-19 
Normal output, 2-16 
Not equal to {^) function, 3-5 
NOT (~) function, 3-6 
UNUM system variable, 4-21 
Number , 

job, C-3 

line, C-4 

negative, 2-3 

project-programmer, C-5, 
D-2 
Number generator, 

random, 4-23 
Number precision, 2-9 
Numbers, 

error, A-1 

lock, 7-38 
Numeric constant, 2-3 
Numeric data, 2-3 
Numeric vector, 2-4 
Numerics to characters, 

converting, 3-64, 3-68 



Object, 

erasing a named, 4-31 
Objects, 

copying, 5-21 
)OFF system command, 1-9, 

5-34 
Operating system command 

level, 5-34 
Operator, 3-1 

inner product, 3-7 

outer product (°), 3^7 3 

reduction (/) , 3-75 

scan (\) , 3-77 
Operators, 3-7 0, B-7 
OR (v) function, 3-6 
Organization , 

file, 7-2 

returning file, 7-31 
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Organization switches, 

file, 7-6 
Origin, 

index, 2-15, 4-19, 5-30 
) ORIGIN system coinmand, 

5-30 
.OU, 4-26, 6-5 
Outer product description, 

3-74 
Outer product (°) operator, 

3-73 
Output , 

array, 2-9 

bare, 2-16 

file, 2-16, 7-4 

function, 6-5 

mixed, 2-16 

normal, 2-16 

quad, 2-16 
Output line width, 4-22 
Output mode, 5-29 
Output precision, 4-22, 5-27 
Output quad (S) function, 
7-16, 7-4, 7-10, 7-21 
) OUTPUT system command, 

7-40 
Over strike characters, 1-7 
Owner , 

workspace, 5-18 
) OWNER system command, 5-18 



Pack, 7-25 
Password, 

workspace, 5-13 
Password setting, 5-15 
)PASSWORD system command, 

5-13 
passwords, 

workspace, 5-6 
)PCOPY system command, 5-25 
Pendent function, 6-18 
Pendent functions, 5-26 
Pi (o) function, 3-3 
Plus (+) function, 3-3 
DPP system variable, 4-22 
Precision, 

number , 2-9 

output, 4-22, 5-27 
Preventing interruptions, 

4-18 
Primitive mixed functions, 

3-10, B-4 
Primitive scalar functions, 

3-2, 3-3, B-2 
Print precision, 4-22 



Procedures, 

character-editing, 6-11, 
6-13 
Product description, 

inner, 3-71 

outer, 3-74 
Product operator, 

inner, 3-70 
Product (°) operator, 

outer, 3-73 
Program, 

running a, 5-35 
Project-programmer number, 

C-5, D-2 
Prompt, 

evaluated input, 4-2 3 

quad, 4-23 
Prompt same line, 2-22 
<prot> , 2-6 

Protected copy, 4-36, 5-25 
Protection, 2-6 

workspace, 5-6 
UPW system variable, 2-20, 

4-22, 5-32 



DQCO system function, 

4-36, 5-21 
UQLD system function, 4-36 
UQPC system function, 

4-36, 5-25 
Quad-divide (g) , 3-50, 3-52 
Quad (D) function, 2-17 
Quad input, 2-16 
Quad (0) function, 

input, 7-4, 7-10, 7-13, 

7-16, 7-20 
Quad (B) function, 

output, 7-4, 7-10, 7-21, 

7-16 
Quad output, 2-16 
Quad prompt, 4-23 
Quad-del (M) function, 2-18 
Quad-del input, 2-16 
Quad-del mode, 2-18, 2-22 
Quad-input mode, 2-17 
Quad-output mode, 2-19 
Question (?) function, 3-3 
Quote (t) function, 3-68 
Quote-quad function (H) , 2-17 
Quote-quad input, 2-16 
Quote-quad mode, 2-17, 2-22 



)R system command, 5-35 
Random access, 7-3 
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Random access file, 7-14 
Random link, 

setting a, 4-23 
Random niomber/ 3-9 
Random number generator, 4-23 
Random seed, 4-23 
Rank, 3-4 3 

Ravel (,) function, 3-36 
Record, 

delete a, 7-17 
Reduction (/) operator, 3-75 
REENTER command, 1-10 
REFUSE LINKS, 4-18 
Relational functions, 3-5, 

B-3 
Relative fuzz, 2-15, 4-14 
Remainder, 3-7 

URENAME system function, 7-8 
Replacing function lines, 

6-8 
Reporting on executing 

functions, 4-20 
Representation , 

canonical, 4-30 
Reshape (p) function, 3-37 
Reshaping an array, 3-37 
Residue function, 3-7 
Result, 

explicit, 6-2, 6-3 
no explicit, 6-2, 6-3 
Retrieving a workspace, 

5-12 
Returning device 

characteristics, 7-33 
Returning file information, 

7-35 
Returning file organization, 

7-31 
Returning to APL, 5-32 
Reverse (4) and e) function, 

3-39 
Rho (p) , 2-5, 3-37, 3-43 
URL system variable, 4-23 
Roll (?) function, 3-9 
Rotate (<t)) function, 3-41 
Rotating an array, 3-41 
RUBOUT, 1-11 

)RUN system command, 5-35 
Running a program, 5-35 



SA, 4-26 
Same line, 

prompt, 2-22 
Save, 

automatic, 4-7 
)SAVE system command, 5-13 



Saving a workspace 

automatically, 4-7 
Saving active workspace, 

5-13 
Scalar, 2-4, 3-1 
Scalar functions, 

primitive, 3-2, 3-3, B-2 
Scan (\) operator, 3-77 
Seal, 

workspace, 5-18 
)SEAL system command, 5-18 
Seed, 

random, 4-23 
Sequential access, 7-2 
Sequential file, 7-9 

ASCII, 7-3 

binary-access, 7-3 

internal, 7-3, 7-13 
Sequential I/O, 

ASCII, 7-10 

internal, 7-13 
Session, 

ending the, 1-9, 5-33 

starting the, 1-8 

terminating the, 5-34 
Session information, 

displaying, 5-36 
SET TTY WIDTH command, 5-32 
Setting, 

password, 5-15 
Setting a random link, 4-23 
USF system variable, 4-23 
Shape (p) function, 3-43 
Share bit, 7-39 

/SHARE switch, 7-4, 7-16, 7-19 
Shared file access, 7-36 
Sharing binary-access files, 

7-19 
Sharing direct-access files, 

7-16 
Sharing information, 

file, 7-34 
Shriek (!), 1-7 
)SI system command, 5-6, 5-2 5, 

6-18, 6-19 
Sign (-) , 

negative, 2-3 
Sign-on time, C-3 
USIGNAL system function, 

4-39, 6-23 
Signalling errors, 4-39 
Significant digits, 5-27 
Single strike characters, 1-6 
Single-user access, 7-16 
)SIV system command, 5-6, 

5-26, 6-19 
Size, 

maximum workspace, 5-16 
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Size (Cont.) 

minimum workspace, 5-17 

workspace, 5-19 
)SIZE system c6mmand, 5-19 
Sleep, 4-31 
Sort, 3-27, 3-28 
Spaces, 2-5 
Specifications, 

file, 2-6 
Specifying TOPS-2 

directories, D-1 
Starting APL, 1-8 
Starting the session, 1-8 
State indicator, 5-6, 5-25 
State indicator, 

clearing the, 6-19, C-5 

displaying the, 5-26 

examining the, 6-18 
Statement, 

assignment, 2-7 

branch, 2-7, 6-14 

conditional branch, 6-15 

unconditional branch, 6-15 
Statement labels, 6-16 
Statement type, 2-7 
Status vector, 5-6 
Stop vector, 6-22 
Stored files, 

deleting, 5-9 
Stored workspaces, 

deleting, 5-9 
Storing account information, 

4-2 
Storing error messages, 

4-16 
Subscripting arrays, 2-11 
Subtraction, 2-3 
Summary, B-1 
Supplying values, 6-3 
Suspended function, 5-2 6 

6-18 
Suspending execution, 4-2 9 
Suspending function 
execution, 6-17 
Switch, 

/AS, 7-6, 7-10 

/AS* 7-6, 7-10 

/BS, 7-6, 7-19, 7-28 

/BS*, 7-6, 7-19 

/BU, 7-19 

/DA, 7-6, 7-16 

/DI, 7-6, 7-16 

/DUMP, 7-4, 7-28 

/file org, 7-4 

/IS, 7-6, 7-13 

/IS*, 7-6, 7-13 

/SHARE, 7-4, 7-16, 7-19 
Switches, 

file organization, 7-6 



Switches (Cont.)f 

)LIB, 5-11 
Symbol classification, 6-3 
Symbol table, 6-3 
Symbol table information, C-1 
Symbols, 

global, 6-4 

local, 6-4 
Synchronizing access, 7-36 
Syntax, 

language, 2-1 
System, 

file, 7-1 
System command, 

)BLOT, 5-36 

)C, 5-32 

)CALL, 5-32 

)CEARGE, 5-36 

) CLEAR, 5-8 

)CONTINUE, 1-9, 5-5, 5-33 

)COPY, 5-21 

)CREATE, 7-15 

)DIGITS, 5-27 

)DROP, 5-9 

)ECHO, 5-28 

) ERASE, 5-22 

)FNS, 5-23 

)GROUP, 5-23 

)GRP, 5-24 

)GRPS, 5-24 

)INPUT, 7-40 

)LIB, 5-10 

)MAXCORE, 5-16 

)MINCORE, 5-17 

)MODE, 5-29 

)MON , 1-9, 5-34 

)OFF, 1-9, 5-34 

)ORIGIN, 5-30 

)OUTPUT, 7-40 

) OWNER, 5-18 

)PASSWORD, 5-13 

)PCOPY, 5-25 

)R, 5-35 

)RUN, 5-35 

)SAVE, 5-13 

)SEAL, 5-18 

)SI, 5-6, 5-25, 6-18, 
6-19 

)SIV, 5-6, 5-26, 6-19 

)SIZE, 5-19 

)TABS, 5-30 

)TIME, 5-19 

)VARS, 5-27 

) VERS I ON, 5-2 

) WIDTH, 5-31 

)WSID, 5-15 
System command format, 5-2 
System command level, 1-9 

operating, 5-34 
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System coininands, 5-1, B-16 
System communication, 4-1 
System function, 

UAPPEND, 1-11, 7-21 

UASS, 7-4 

UBREAK, 4-29, 6-23 

UCHS, 7-31 

UCIQ, 7-25 

UCLS, 1-1 

UCOQ, 7-25 

UCR, 4-30, 4-33 

UDAS, 7-6 

UDEQ, 7-36 

UDL, 4-31 

UDVC, 7-33 

Dfi'i^^, 7-36 

UEX, 4-31 

DFCii^, 7-35 

DFJ, 4-32, 4-40 

UFLS, 7-34 

DFZ, 4-33 

UMTP, 7-28 

D-A?C, 4-34 

UBL, 4-35 

D^CO, 4-36, 5-21 

UQLD, 4-36, 5-12 

DSPC, 4-36, 5-25 

ORE NAME, 7-8 

D-SIG'^^L, 4-39, 6-23 

UVI, 4-40 
System functions, 4-1, 4-28, 

B-11 
System functions, 

file, B-12 
System variable, 

D^J, 4-2 

UALPHA, 4-3 

UALPHAU, 4-3 

DASCII, 4-3, 4-4 

UAUS, 4-7 

UAV, 4-8, 4-9 

DCT, 2-15, 4-14 

UCTRL, 4-15 

DERROR, 4-16, 6-23 

DG4G, 4-18 

DJO, 4-19 

QLC, 4-20, 6-18 

DLZ, 4-20 

UNUM, 4-21 

DPP A — 21. 

UPw', 2-20, 4-22, 5-32 

ni?z:, 4-23 

USE, 4-23 
UTIMELIMIT , 4-24 
UTIMEOUT, 4-24 
ni'i?^?, 4-25, 6-23 
DTJ, 4-27 
D^T, 4-27 
Di/L, 4-28 



System variable (Cont.), 

nWA, 4-28 
System variables, 4-1, 4-2, 

B-9 



TA, 4-26 

Tab stops, 5-30 

Table, 

symbol, 6-3 
Tables, 

formatting, 3-65 
)TABS system command, 5-30 
Take (+) function, 3-4 5 
Terminal character set, C-4 
/terminal, 1-3, 7-40 
Terminal designators, 1-2, 

1-3 
Terminal I/O, 2-16 
Terminal mode, 5-29 
Terminal time out, 4-24 
Terminal type, 4-27 
TERMINAL WIDTH command, 

5-32 
Terminals , 

APL-keyboard , 1-3 

TTY, 1-5 
Terminating the session, 

5-34 
Termination commands, 

APL, 5-32 
Time, 

connect, 5-19 

CPU, 4-2, 5-19, C-2 

current, 4-27 

keying, C-2 

sign-on, C-3 
Time limit, 4-24 
Time limit indicator, 4-24 
Time of day, C-2 
Time out, 

terminal, 4-24 
)TIME system command, 5-19 
Time used, 5-19, C-6 
UTIMELIMIT system variable, 

4-24 
UTIMEOUT system variable, 

4-24 
.TMP file, 4-8 
Tolerance, 

comparison, 2-15, 4-14 
TOPS-20 directories, 

specifying, D-1 
Trace vector, 6-2 
TRANSL command, D-2 
Transpose definitions, 3-48 
Transpose (^) function, 

dyadic, 3-48 
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Transpose (<s?) function, (Cont.) 

monadic, 3-4 6 
Transposing dimensions, 

3-46 
UTRAP system variable, 4-25, 

6-23 
Trapping, 

error, 6-23 
Trapping errors, 4-25 
Trapping examples, 

error, 6-24 
UTS system variable, 4-27 
UTT system variable, 4-27 
TTY NO GAG, 4-18 
TTY set, 1-6 
TTY terminals, 1-5 
.typ, 2-6 

Type, 7-20, 7-21, 7-25 
Type, 

statement, 2-7 



UUL system variable, 4-28 
Unconditional branch 

statement, 6-15 
Underlined alphabetics, 4-3 
Underscore (_) , 1-7 
Unedited input, 2-16 
Unedited- input mode, 2-18 
Unpack, 7-2 5 

Unquote (i) function, 3-54 
Up union (u) , 1-7 
User Identification, 4-2 
User-defined function, 6-1 



Validating input, 4-4 
Values, 

supplying, 6-3 
Variable, 

UAI system, 4-2 

UALPHA system, 4-3 

UALPHAU system, 4-3 

UASCII system, 4-3, 4-4 

UAUS system, 4-7 

0.47 system, 4-8, 4-9 

UCT system, 2-15, 4-14 

UCTRL system, 4-15 

UERROR system, 4-16, 6-23 

UGAG system, 4-18 

UIO system, 4-19 

ULC system, 4-20, 6-18 

ULX system, 4-21 

UNUM system, 4-21 

UPP system, 4-22 

UPW system, 2-20, 4-22, 5-32 

URL system, 4-23 



Variable (Cont.)f 

USF system, 4-23 

UTIMELIMIT system, 4-24 

UTIMEOUT system, 4-24 

UTRAP system, 4-25, 6-23 

UTS system, 4-27 

UTT system, 4-27 

UUL system, 4-28 

WA system, 4-2 8 
Variable list, 

displaying a, 5-27 
Variable name, 6-3 
Variables, 

system, 4-1, 4-2, B-9 
)VARS system command, 5-27 
Vector, 2-4 

atomic, 4-9 

character, 2-4 

literal, 2-4 

numeric, 2-4 

status, 5-6 

stop, 6-22 

trace, 6-20 
Version number, 5-20 
) VERSION system command, 

5-20 
UVI system function, 4-4 



UWA system variable, 4-28 
Width, 

output line, 4-22 
) WIDTH system command, 5-31 
Work area, 

available, 4-28 
Workspace, 

active, 1-1, 5-3 

clear, 1-1 

clearing the active, 5-8 

CONTIN, 5-5 

CONTINUE, 5-5 

copying a, 4-36 

identifying the active, 
5-15 

inactive, 1-1 

loading a, 4-36 

retrieving a, 5-12 

saving active, 5-13 
Workspace automatically, 

saving a, 4-7 
Workspace availability, C-3 
Workspace characteristics, 

5-3 
Workspace I.D., 5-15 
Workspace names, 5-4 

listing, 5-10 
Workspace owner, 5-18 
Workspace password, 5-13 
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Workspace passwords, 5-6 
Workspace protection, 5-6 
Workspace seal, 5-18 
Workspace size, 5-19 

maximum, 5-16 

minimum, 5-17 
Workspace-content commands, 
5-20 



Workspace-control commands, 

5-7 
Workspace-environment 

commands, 5-27 
Workspaces, 

deleting stored, 5-9 
Writing a function, 6-1 
)WSID system command, 5-15 



Index-15 



APLSF Language Manual 
AA-H200A-TK 



READER'S COMMENTS 



NOTE: This form is for document comments only. DIGITAL will 
use comments submitted on this form at the company's 
discretion. If you require a written reply and are 
eligible to receive one under Software Performance 
Report (SPR) service, submit your comments on an SPR 
form. 

Did you find this manual understandable, usable, and well-organized? 
Please make suggestions for improvement. 



Did you find errors in this manual? If so, specify the error and the 
page number. 



Please indicate the type of reader that you most nearly represent. 

I I Assembly language programmer 

I I Higher- level language programmer 

I I Occasional programmer (experienced) 

I I User with little programming experience 

I I Student programmer 

I I Other (please specify) 



Name Date. 



Organization Telephone 

Street 



City State Zip Code. 

or 
Country 



Do Not Tear — Fold Here and Tape 




No Postage 

Necessary 

if Mailed in the 

United States 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 33 MAYNARD MASS. 



POSTAGE WILL BE PAID BY ADDRESSEE 

SOFTWARE PUBLICATIONS 

200 FOREST STREET MR1-2/E37 
MARLBOROUGH. MASSACHUSETTS 01752 



Do Not Tear — Fold Here and Tape 



